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Prefacio 


PHP,  acronimo  de  "PHP:  Hypertext  Preprocessor",  es  un  lenguaje  interpretado  de  alto  nivel  embebido  en 
paginas  HTML.  La  mayorfa  de  su  sintaxis  es  similar  a  C,  Java  y  Perl,  con  solamente  un  par  de 
caracteristicas  PHP  especificas.  La  meta  de  este  lenguaje  es  permitir  escribir  a  los  creadores  de  paginas 
web,  paginas  dinamicas  de  una  manera  rapida  y  facil. 


Sobre  este  Manual 


Este  manual  esta  escrito  en  SGML  usando  DocBook  DTD  (http://www.ora.com/davenport/)  y  DSSSL 
(http://www.jclark.com/dsssl/)  (Document  Style  and  Semantics  Specification  Language)  para  su 
creacion.  Las  herramientas  usadas  para  crear  las  versiones  HTML,  TeX  y  RTF  son  Jade 
(http://www.jclark.com/jade/),  escrita  por  James  Clark  (http://www.jclark.com/bio.htm)  y  The  Modular 
DocBook  Stylesheets  (http://nwalsh.com/docbook/dsssl/)  escrita  por  Norman  Walsh 
(http://nwalsh.com/).  El  marco  de  trabajo  de  la  documentacion  de  PHP  fue  creado  por  Stig  Saether 
Bakken  (mailto:stig@php.net). 


Sobre  la  traduccion 


La  traduccion  del  manual  de  PHP  al  espanol  ha  sido  posible  gracias  a  la  colaboracion  de  un  gran  numero 
de  traductores,  que  desinteresadamente  han  usado  su  tiempo  para  que  todos  podamos  tener  una  version 
en  nuestra  lengua  de  esta  documentacion. 

(Aqui  vendra  la  lista  de  colaboradores) 


i 


Parte  I.  Conceptos  Basicos 

Capi'tulo  1.  Introduccion 


Que  es  PHP? 


Capitulo  1.  Introduction 


PHP  (acronimo  de  "PHP:  Hypertext  Preprocessor")  es  un  lenguaje  interpretado  de  alto  nivel  embebido  en 
paginas  HTML  y  ejecutado  en  el  servidor. 

Una  respuesta  corta  y  concisa,  pero  que  significa  realmente?  Un  ejemplo  nos  aclarara  las  cosas: 


Ejemplo  1-1.  Un  ejemplo  introductorio 

<html> 

<head> 

<title>E jemplo  PHP</title> 

</head> 

<body> 

<?php  echo  "Hola,  este  es  un  ejemplo  con  PHP!";  ?> 
</body> 

</html> 


Podemos  ver  que  no  es  lo  mismo  que  un  script  CGI  escrito  en  otro  lenguaje  de  programacion  como  Perl 
o  C  —  En  vez  de  escribir  un  programa  con  muchos  comandos  para  crear  una  salida  en  HTML,  escribimos 
el  codigo  HTML  con  cierto  codigo  PHP  embebido  (introducido)  en  el  mismo,  que  producira  cierta  salida 
(en  nuestro  ejemplo,  producir  un  texto).  El  codigo  PHP  se  incluye  entre  etiquetas  especiales  de  comienzo 
y  final  que  nos  permitiran  entrar  y  salir  del  modo  PHP 

Lo  que  distingue  a  PHP  de  la  tecnologfa  Javascript,  la  cual  se  ejecuta  en  la  ma;quina  cliente,  es  que  el 
codigo  PHP  es  ejecutado  en  el  servidor.  Si  tuviesemos  un  script  similar  al  de  nuestro  ejemplo  en  nuestro 
servidor,  el  cliente  solamente  recibirfa  el  resultado  de  su  ejecucion  en  el  servidor,  sin  ninguna  posibilidad 
de  determinar  que  codigo  ha  producido  el  resultado  recibido.  El  servidor  web  puede  ser  incluso 
configurado  para  que  procese  todos  los  ficheros  HTML  con  PHP. 


Que  se  puede  hacer  con  PHP? 

Al  nivel  mas  basico,  PHP  puede  hacer  cualquier  cosa  que  se  pueda  hacer  con  un  script  CGI,  como 
procesar  la  informacion  de  formularios,  generar  paginas  con  contenidos  dinamicos,  o  mandar  y  recibir 
cookies. 

Quizas  la  caracterfstica  mas  potente  y  destacable  de  PHP  es  su  soporte  para  una  gran  cantidad  de  bases 
de  datos.  Escribir  un  interfaz  via  web  para  una  base  de  datos  es  una  tarea  simple  con  PHP.  Las  siguientes 
bases  de  datos  estan  soportadas  actualmente: 

Adabas  D  Ingres  Oracle  (OCI7  and  OCI8) 
dBase  InterBase  PostgreSQL 
Empress  FrontBase  Solid 
FilePro  mSQL  Sybase 
IBM  DB2  MySQL  Velocis 
Informix  ODBC  Unix  dbm 

PHP  tambien  soporta  el  uso  de  otros  servicios  que  usen  protocolos  como  IMAP,  SNMP,  NNTP,  POP3, 
HTTP  y  derivados.  Tambien  se  pueden  abrir  sockets  de  red  directos  (raw  sockets)  e  interactuar  con  otros 
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protocolos. 


Corta  historia  de  PHP 


PHP  fue  concebido  en  otono  de  1994  por  Rasmus  Lerdorf  (mailto:rasmus@php.net).  Las  primeras 
versiones  no  distribuidas  al  publico  fueron  usadas  en  un  sus  paginas  web  para  mantener  un  control  sobre 
quien  consultaba  su  curriculum.  La  primera  version  disponible  para  el  publico  a  principios  de  1995  fue 
conocida  como  "Herramientas  para  paginas  web  personales"  (Personal  Home  Page  Tools).  Consistian  en 
un  analizador  sintactico  muy  simple  que  solo  entendia  unas  cuantas  macros  y  una  serie  de  utilidades 
comunes  en  las  paginas  web  de  entonces,  un  libro  de  visitas,  un  contador  y  otras  pequenas  cosas.  El 
analizador  sintactico  fue  reescrito  a  mediados  de  1995  y  fue  nombrado  PHP/FI  version  2.  FI  viene  de 
otro  programa  que  Rasmus  habia  escrito  y  que  procesaba  los  datos  de  formularios.  Asi  que  combino  las 
"Herramientas  para  paginas  web  personales",  el  "interprete  de  formularios",  anadio  soporte  para  mSQL  y 
PHP/FI  vio  la  luz.  PHP/FI  crecio  a  gran  velocidad  y  la  gente  empezo  a  contribuir  en  el  codigo. 

Es  diffcil  dar  estadfsticas  exactas,  pero  se  estima  que  a  finales  de  1996  PHP/FI  se  estaba  usando  al  menos 
en  15.000  paginas  web  alrededor  del  mundo.  A  mediados  de  1997  este  numero  habia  crecido  a  mas  de 
50.000.  A  mediados  de  1997  el  desarrollo  del  proyecto  sufrio  un  profundo  cambio,  dejo  de  ser  un 
proyecto  personal  de  Rasmus,  al  cual  habian  ayudado  un  grupo  de  usuarios  y  se  convirtio  en  un  proyecto 
de  grupo  mucho  mas  organizado.  El  analizador  sintactico  se  reescribio  desde  el  principio  por  Zeev 
Suraski  y  Andi  Gutmans  y  este  nuevo  analizador  establecio  las  bases  para  PHP  version  3.  Gran  cantidad 
de  codigo  de  PHP/FI  fue  portado  a  PHP3  y  otra  gran  cantidad  fue  escrito  completamente  de  nuevo. 

Hoy  en  dfa  (finales  1999),  tanto  PHP/FI  como  PHP3  se  distribuyen  en  un  gran  numero  de  productos 
comerciales  tales  como  el  servidor  web  "C2’s  StrongHold"  y  Redhat  Linux.  Una  estimation  conservativa 
basada  en  estadlsticas  de  NetCraft  (http://www.netcraft.com/)  (ver  tambien  Estudio  de  NetCraft  sobre 
servidores  web  (http://www.netcraft.com/survey/)),  es  que  mas  de  1.000.000  de  servidores  alrededor  del 
mundo  usan  PHP.  Para  hacernos  una  idea,  este  numero  es  mayor  que  el  numero  de  servidores  que 
utilizan  el  "Netscape’s  Enterprise  server"  en  Internet. 

A  la  vez  que  todo  esto  esta  pasando,  el  trabajo  de  desarrollo  de  la  proxima  generation  de  PHP  esta  en 
marcha.  Esta  version  utiliza  el  potente  motor  de  scripts  Zend  (http://www.zend.com/)  para  proporcionar 
altas  prestaciones,  asf  como  soporta  otros  servidores  web,  ademas  de  apache,  que  corren  PHP  como 
modulo  nativo. 


3 


Capi'tulo  2.  Instalacion 


4 


Capitulo  2.  Instalacion 


Bajandose  la  ultima  version 

El  codigo  fuente  y  las  distribuciones  binarias  para  algunas  plataformas  (inclmdo  Windows)  se  pueden 
encontrar  en  http :  / /www . php .  net/. 


Instalacion  en  sistemas  UNIX 

Esta  seccion  le  guiara  a  traves  de  la  configuration  e  instalacion  del  PHP.  Conocimientos  y  software 
necesarios: 

•  Habilidades  basicas  en  UNIX  (ser  capaz  de  manejar  el  "make"  y  un  compilador  de  C) 

•  Un  compilador  ANSI  de  C 

•  Un  servidor  web 


Instrucciones  Rapidas  de  Instalacion  (Version  Modulo  de  Apache) 

1.  gunzip  apache_l . 3 . x . tar . gz 

2.  tar  xv f  apache_l . 3 . x . tar 

3.  gunzip  php-3 . 0 . x . tar . gz 

4.  tar  xvf  php-3 . 0 . x . tar 

5.  cd  apache_1.3.x 

6.  ./configure  — prefix=/www 

7.  cd  ../php-3. 0.x 

8.  ./configure  — with-mysql  — with-apache= . . /apache_l . 3 . x  — enable-track-vars 

9 .  make 

10.  make  install 

11.  cd  . . /apache_l . 3 . x 

12.  ./configure  — prefix=/www  — activate-module=src/modules/php3/libphp3 . a 

13.  make 

14.  make  install 

En  lugar  de  este  paso  quizas  prefiera  simplemente  copiar  el  binario 
httpd  encima  del  binario  existente.  Si  lo  hace,  asegurese  antes  de 
cerrar  su  servidor. 

15.  cd  ../php-3. 0.x 

16.  cp  php3 . ini-dist  /usr/local/lib/php3 . ini 

Puede  editar  el  archivo  /usr/local/lib/php3 . ini  para  ajustar  opciones 
del  PHP.  Si  prefiere  tenerlo  en  otro  sitio,  utilice 
— with-conf ig-f ile-path=/path  en  el  paso  8. 

17.  Edite  su  archivo  httpd. conf  o  srm.conf  y  anada : 
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AddType  application/x-httpd-php3  .php3 

Puede  elegir  la  extension  que  desee  aqui.  .php3  es  simplemente  nuestra 
sugerencia . 

18.  Utilice  su  metodo  habitual  para  iniciar  el  servidor  Apache  (debe  detener 
y  reiniciar  el  servidor,  no  solamente  hacerlo  recargarse  usando  una 
senal  HUP  o  USR1 . ) 


Configuracion 

Hay  dos  maneras  de  configurar  el  PHP. 


•  Utilizando  el  script  de  "setup"  que  viene  con  el  PHP.  Este  script  le  hace  una  serie  de  preguntas  (casi 
como  el  script  "install"  del  PHP/FI  2.0)  y  ejecuta  el  "configure"  al  final.  Para  ejecutar  este  script, 
escriba  ./setup. 

Este  script  tambien  creara  un  archivo  llamado  "do-conf",  que  contendra  las  opciones  pasadas  a  la 
configuracion.  Puede  editar  este  archivo  para  cambiar  algunas  opciones  sin  tener  que  re -ejecutar  el 
"setup".  Escriba  luego  ./do-conf  para  ejecutar  la  configuracion  con  las  nuevas  opciones. 


•  Ejecutar  el  "configure"  a  mano.  Para  ver  las  opciones  de  que  dispone,  escriba  ./configure  —help. 


Los  detalles  sobre  las  distintas  opciones  de  configuracion  son  listados  a  continuacion. 


Modulo  del  Apache 

Para  configurar  el  PHP  como  modulo  de  Apache,  responda  "yes"  a  "Build  as  an  Apache  module?"  (la 
opcion  — with-apache  =dir  es  la  que  lo  configura)  y  especifique  el  directorio  base  de  la  distribucion 
de  Apache.  Si  ha  desempacado  el  Apache  en  /usr/local/www/apache_l  .2.4,  este  sera  su  directorio 
base  de  la  distribucion  de  Apache.  El  directorio  por  defecto  es  /usr/local/etc/httpd. 


Modulo  fhttpd 

Para  configurar  el  PHP  como  modulo  fhttpd,  responda  "yes"  a  "Build  as  an  fhttpd  module?"  (la  opcion 
— with- fhttpd  =dir  es  la  que  lo  configura)  y  especifique  el  directorio  base  del  fuente  del  fhttpd.  El 
directorio  por  defecto  es  /usr/local/src/fhttpd.  Si  esta  ejecutando  fhttpd,  configurar  PHP  como 
modulo  le  dara  mejor  rendimiento,  mas  control  y  capacidad  de  ejecucion  remota. 
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CGI  version 

El  valor  por  defecto  es  configurar  el  PHP  como  programa  CGI.  Si  esta  ejecutando  un  servidor  web  para 
el  que  el  PHP  tiene  soporte  como  modulo,  deberfa  elegir  dicha  solucion  por  motivos  de  rendimiento.  Sin 
embargo,  la  version  CGI  permite  a  los  usuarios  del  Apache  el  ejecutar  distintas  paginas  con  PHP  bajo 
distintos  identific adores  de  usuario.  Por  favor,  asegurese  de  haber  lefdo  el  capitulo  sobre  Seguridad  si  va 
a  ejecutar  el  PHP  como  CGI. 


Opciones  de  soporte  para  Base  de  Datos 

El  PHP  tiene  soporte  nativo  para  bastantes  bases  de  datos  (asf  como  para  ODBC): 


Adabas  D 


— with-adabas=.DX.R 


Compila  con  soporte  para  Adabas  D.  El  parametro  es  el  directorio  de  instalacion  de  Adabas  D  y  por 
defecto  vale  /usr/local/adabasd. 

Pagina  de  Adabas  (http://www.adabas.com/) 


dBase 


— with-dbase 


Habilita  el  soporte  integrado  para  DBase.  No  se  precisan  librerfas  externas. 


filePro 

— with- filepro 


Habilita  el  soporte  integrado  de  solo  lectura  para  filePro.  No  se  precisan  librerfas  externas. 


mSQL 


— with-msql =DIR 


Habilita  el  soporte  para  mSQL.  El  parametro  es  el  directorio  de  instalacion  de  mSQL  y  por  defecto  vale 
/usr/local/Hughes.  Este  es  el  directorio  por  defecto  de  la  distribution  mSQL  2.0.  configure  detecta 
automaticamente  que  version  de  mSQL  esta  ejecutandose  y  el  PHP  soporta  tanto  1.0  como  2.0,  pero  si 
compila  el  PHP  con  mSQL  1 .0  solo  podra  acceder  a  bases  de  datos  de  esa  version  y  viceversa. 

Vea  tambien  Directivas  de  Configuracion  de  mSQL  en  el  archivo  de  configuracion 
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Pagina  de  mSQL  (http://www.hughes.com.au) 

MySQL 


— with-mysql=DJ.R 


Habilita  el  soporte  para  MySQL.  El  parametro  es  el  directorio  de  instalacion  de  MySQL  y  por  defecto 
vale  /usr/local.  Este  es  el  directorio  de  instalacion  de  la  distribution  de  MySQL. 

Vea  tambien  Directivas  de  Configuration  de  MySQL  en  el  archivo  de  configuration 

Pagina  de  MySQL  (http://www.tcx.se) 


iODBC 


— with-iodbc=£>J.R 


Incluye  soporte  para  iODBC.  Esta  caracterfstica  se  desarrollo  inicialmente  para  el  iODBC  Driver 
Manager,  un  gestor  de  controlador  de  ODBC  de  redistribution  libre  que  ese  ejecuta  bajo  varios  sabores 
de  UNIX.  El  parametro  es  el  directorio  de  instalacion  de  iODBC  y  por  defecto  vale  /usr/local. 

Pagina  de  FreeODBC  (http://users.ids.net/~bjepson/freeODBC/)  o  pagina  de  iODBC 
(http://www.iodbc.org) 


OpenLink  ODBC 

— with-openlink=DJJ? 


Incluye  soporte  para  OpenLink  ODBC.  El  parametro  es  el  directorio  de  instalacion  de  OpenLink  ODBC 
y  por  defecto  vale  / usr/local/ openlink. 

Pagina  de  OpenLink  Software  (http://www.openlinksw.com/) 


Oracle 


— with-oracle=DJiR 


Incluye  soporte  para  Oracle.  Se  ha  probado  y  deberfa  funcionar  al  menos  con  las  versiones  de  la  7.0  a  la 
7.3.  El  parametro  es  el  directorio  ORACLE_HOME.  No  necesita  especificar  este  parametro  si  su  entorno 
de  Oracle  ya  esta  ajustado. 

Pagina  de  Oracle  (http://www.oracle.com) 
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PostgreSQL 


— with-pgsql=£>J.R 


Incluye  soporte  para  PostgreSQL.  El  parametro  es  el  directorio  base  de  la  instalacion  de  PostgreSQL  y 
por  defecto  vale  /usr/local/pgsql. 

Vea  tambien  Directivas  de  Configuracion  de  Postgres  en  el  archivo  de  configuracion 
Pagina  de  PostgreSQL  (http://www.postgreSQL.org/) 


Solid 


— with- sol  i-d=DIR 


Incluye  soporte  para  Solid.  El  parametro  es  el  directorio  de  instalacion  y  vale  por  defecto 

/usr/ local/ solid. 

Pagina  de  Solid  (http://www.solidtech.com) 


Sybase 


— with- Sybase =D I R 


Incluye  soporte  para  Sybase.  El  parametro  es  el  directorio  de  instalacion  y  vale  por  defecto 

/home/sybase. 

Vea  tambien  Directivas  de  Configuracion  de  Sybase  en  el  archivo  de  configuracion 
Pagina  de  Sybase  (http://www.sybase.com) 


Sybase-CT 


— with-sybase-ct=.DX.R 


Incluye  soporte  para  Sybase-CT.  El  parametro  es  el  directorio  de  instalacion  de  Sybase-CT  y  por  defecto 
vale  /home/sybase. 

Vea  tambien  Directovas  de  Configuracion  de  Sybase-CT  en  el  archivo  de  configuracion 


Velocis 


— with-velocis=DJiR 
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Incluye  soporte  para  Velocis.  El  parametro  es  el  directorio  de  instalacion  de  Velocis  y  vale  por  defecto 

/usr/ local/ velocis. 

Pagina  de  Velocis  (http://www.raima.com) 


Una  libreria  a  medida  de  ODBC 

— with-custom-odbc=DI.R 


Incluye  soporte  para  una  libreria  a  medida  arbitraria  de  ODBC.  El  parametro  es  el  directorio  base  y  por 
defecto  vale  /usr/local. 

Esta  opcion  implica  que  se  ha  definido  CUSTOM_ODBC_LIBS  cuando  se  ejecuto  el  script  de 
configuracion.  Tambien  debera  tener  una  cabecera  odbc.h  valida  en  algun  lugar  de  su  sendero  (path)  de 
inclusion.  Si  no  tiene  uno,  creelo  e  incluya  su  cabecera  especffica  desde  ahf.  Su  cabecera  puede  requerir 
algunas  definiciones  extra,  particularmente  si  es  multiplataforma.  Defmalas  en  CFLAGS. 

Por  ejemplo,  puede  usar  Sybase  SQL  Anywhere  bajo  QNX  como  sigue:  CFLAGS=-dodbc_QNX 
LDFLAGS=— lunix  CUSTOM_ODBC_LIBS="-ldblib  -lodbc"  ./configure 
— with-custom-odbc=/usr/lib/ sqlany50 


ODBC  Unificado 

— di s able -uni f ied-odbc 


Deshabilita  el  modulo  de  ODBC  Unificado,  que  es  un  interfaz  comun  a  todas  las  bases  de  datos  con 
interfaces  basados  en  ODBC,  tales  como  Solid  y  Adabas  D.  Tambien  funciona  para  librerfas  normales  de 
ODBC.  Ha  sido  probado  con  iODBC,  Solid,  Adabas  D  y  Sybase  SQL  Anywhere.  Requiere  que  uno  (y 
solo  uno)  de  estos  modulos  o  el  modulo  de  Velocis  este  habilitado,  o  que  se  especifique  una  libreria  a 
medida  de  ODBC.  Esta  opcion  solo  se  puede  aplicar  si  alguna  de  estas  opciones  es  usada:  — with-iodbc 
— ■ with-solid ,  — with-adabas ,  — with-velocis ,  o  — with-custom-odbc 

Vea  tambien  Directivas  de  Configuracion  de  ODBC  Unificado  en  el  archivo  de  configuracion 


LDAP 


— with-ldap=DI.R 


Incluye  soporte  para  LDAP  (Lightweight  Directory  Access  Protocol  -  Protocolo  Ligero  de  Acceso  a 
Directorios).  El  parametro  es  el  directorio  base  de  instalacion  de  LDAP,  y  por  defecto  vale 

/ usr/ local /ldap. 

Puede  encontrar  mas  informacion  sobre  LDAP  en  RFC1777  (ftp://ftp.isi.edu/in-notes/rfcl777.txt)  y  en 
RFC  1778  (ftp://ftp.isi.edu/in-notes/rfcl778.txt). 
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-with-mcrypt=DJj? 

— with-mcrypt 


Incluye  soporte  para  la  librerfa  mcrypt.  Vea  la  documentacion  de  mcrypt  para  mas  informacion.  Si  utiliza 
el  argumento  opcional  DIR,  el  PHP  buscara  mcrypt. h  en  DlP/include. 


--enable-sysvsem 

— enable-sysvsem 


Incluye  soporte  para  semaforos  Sys  V  (soportados  por  muchos  derivados  Unix).  Vea  la  documentacion 
sobre  Semaforos  y  Memoria  Compartida  para  mas  informacion. 


--enable-sysvshm 

— enable-sysvshm 


Incluye  soporte  para  la  memoria  compartida  Sys  V  (soportada  por  muchos  derivados  Unix).  Vea  la 
documentacion  sobre  Semaforos  y  Memoria  Compartida  para  mas  informacion. 


--with-xml 


— with-xml 


Incluye  soporte  para  un  parser  XML  no  validador  que  utiliza  la  librerfa  expat 

(http://www.jclark.com/xml/)  de  James  Clark.  Vea  la  referencia  de  funciones  XML  para  mas  detalles. 


--enable-maintainer-mode 

— enable-maintainer-mode 


Activa  avisos  extra  de  dependencias  y  del  compilador  utilizados  por  algunos  de  los  desarrolladores  del 
PHP. 
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-with-system-regex 

— with-system-regex 


Utiliza  la  librerfa  de  expresiones  regulares  del  sistema  en  lugar  de  la  inclufda.  Si  esta  compilando  PHP 
como  modulo  de  servidor,  debe  utilizar  la  misma  librerfa  cuando  genere  el  PHP  y  cuando  lo  enlace  con 
el  servidor.  Active  esto  si  la  librerfa  del  sistema  proporciona  caracterfsticas  especiales  que  pueda 
necesitar.  Se  recomienda  utilizar  la  librerfa  inclufda  siempre  que  sea  posible. 


-with-config-file-path 

— with-conf ig- file-pat h=DIR 


El  path  utilizado  para  buscar  el  archivo  de  configuration  cuando  arranca  el  PHP 


--with-exec-dir 


— with-exec-dir=DJR 


Solo  permite  ejecutar  programas  en  DIR  cuando  esta  en  modo  seguro.  Por  defecto  vale 
/usr/ local/bin.  Esta  opcion  solo  fija  el  valor  por  defecto.  Puede  ser  cambiado  posteriormente 
mediante  la  directiva  safe_mode_exec_dir  en  el  fichero  de  configuracion  . 


--enable-debug 

— enable-debug 


Habilita  informacion  de  depuracion  adicional.  Esto  hace  posible  obtener  information  mas  detallada 
cuando  hay  problemas  con  el  PHP.  (Notese  que  esto  no  tiene  que  ver  con  las  facilidades  de  depuracion  o 
con  la  informacion  disponible  para  los  script  PHP). 


--enable-safe-mode 

— enable-safe-mode 


Habilita  el  "modo  seguro"  por  defecto.  Esto  impone  varias  restricciones  sobre  lo  que  el  PHP  puede  hacer, 
tales  como  abrir  fichero  solo  en  el  raiz  de  documentos.  Lea  el  capitulo  de  Seguridad  para  mas 
information.  Los  usuarios  de  CGI  deberan  siempre  habilitar  el  modo  seguro.  Esta  option  solo  fija  el 
valor  por  defecto.  Puede  ser  habilitado  o  deshabilitado  posteriormente  mediante  la  directiva  safe_mode 
en  el  archivo  de  configuracion 
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--enable-track-vars 

— enable-track-vars 


Hace  que  el  PHP  lleve  el  control  de  donde  proceden  las  variables  GET/POST/cookie  usando  las  matrices 
HTTP_GET_ VARS ,  HTTP_POST_VARS  y  HTTP_COOKIE_VARS.  Esta  opcion  solo  fija  el  valor  por 
defecto.  Puede  ser  habilitado  o  deshabilitado  posteriormente  mediante  la  directiva  track_vars  en  el 
archivo  de  configuracion 


--enable-magic-quotes 

— enable-magic-quotes 


Habilita  las  comillas  magicas  por  defecto.  Esta  opcion  solo  fija  el  valor  por  defecto.  Puede  ser  habilitada 
o  deshabilitada  posteriormente  mediante  la  directiva  magic_quotes_runtime  en  el  archivo  de 
configuracion  Vea  tambien  las  directivas  magic_quotes_gpc  y  magic_quotes_sybase 


--enable-debugger 

— enable-debugger 


Habilita  el  soporte  de  depuracion  interno  del  PHP.  Esta  caracterfstica  aun  esta  en  estado  experimental. 
Vea  tambien  las  directivas  de  Configuracion  del  Depurador  en  el  archivo  de  configuracion 


--enable-discard-path 

— enable-dis card-path 


Si  esta  habilitado,  el  ejecutable  CGI  del  PHP  se  puede  situar  tranquilamente  fuera  del  arbol  de  la  web  y 
la  gente  no  podra  saltarse  la  seguridad  del  .htaccess.  Lea  la  seccion  en  el  capitulo  de  seguridad  sobre  esta 
opcion. 


-enable-bcmath 

— enable-bcmath 


Habilita  las  funciones  matematicas  de  precision  arbitraria  estilo  be.  Vea  tambien  la  opcion  bemath. scale 
en  el  archivo  de  configuracion 
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-enable-force-cgi-redirect 

— enable-force-cgi-redirect 


Habilita  la  comprobacion  de  seguridad  para  redirecciones  internas  del  servidor.  Debera  usar  esta  opcion 
si  esta  ejecutando  la  version  CGI  bajo  Apache. 

Cuando  se  utiliza  el  PHP  como  un  ejecutable  CGI,  siempre  compmeba  primero  is  esta  siendo  utilizado 
bajo  redireccion  (por  ejemplo  bajo  Apache,  usando  directivas  Action).  Esto  asegura  que  el  ejecutable  del 
PHP  no  se  puede  usar  para  saltarse  los  mecanismos  estander  de  autentificacion  del  servidor  web 
llamando  al  ejecutale  directamente,  como  en  http:  //my . host/cgi-bin/php/secret/doc . html. 
Este  ejemplo  accede  al  archivo  http :  //my .  host/secret/doc .  html  pero  sin  respetar  ningun  ajuste 
de  seguridad  del  httpd  para  el  directorio  /  secret. 

No  habilitando  esta  opcion  se  deshabilita  la  comprobacion  y  se  permite  el  saltarse  los  ajustes  de 
seguridad  y  autenticacion  del  httpd.  Haga  esto  solo  si  el  software  de  su  servidor  no  puede  indicar  que  se 
ha  realizado  una  redireccion  segura  y  que  todos  sus  archivos  bajo  la  raiz  de  documentos  y  los  directorios 
de  los  usuarios  pueden  ser  accedidos  por  cualquiera. 

Lea  la  seccion  en  el  capitulo  de  seguridad  acerca  de  esta  opcion. 


--disable-short-tags 

— disable-short-tags 


Deshabilita  las  etiquetas  de  PHP  en  formato  corto  <?  ?>.  Debe  deshabilitar  el  formato  corto  si  desea 
usar  PHP  con  XML.  Con  el  formato  corto  deshabilitado,  la  unica  etiqueta  de  codigo  de  PHP  es  <?php 
?>.  Esta  opcion  solo  fija  el  valor  por  defecto.  Puede  ser  habilitada  o  deshabilitada  posteriormente 
mediante  la  directiva  short_open_tag  en  el  archivo  de  configuration 


--enable-url-includes 

— enable-url-includes 


Hace  posible  ejecutar  codigo  en  otros  servidores  HTTP  o  FTP  directamente  desde  el  PHP  usando 
includeQ  Vea  tambien  la  opcion  include_path  en  el  archivo  de  configuration 


--disable-syntax-hl 

— disable-syntax-hl 


Desconecta  el  resalte  de  sintaxis. 
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CPPFLAGS y  LDFLAGS 

Para  hacer  que  la  instalacion  de  PHP  busque  los  archivos  de  cabecera  o  de  librerfa  en  distintos 
directorios,  modifique  las  variables  de  entorno  CPPFLAGS  y  LDFLAGS  respectivamente.  Si  esta 
utilizando  un  shell  "sensible",  podra  ejecutar  LDFLAGS=-L/my/lib/dir 
CPPFLAGS=-I/my/include/dir  ./configure 


Construyendo 

Cuando  el  PHP  esta  configurado,  ya  esta  listo  para  construir  el  ejecutable  CGI  o  la  librerfa  PERL.  El 
comando  make  deberfa  ocuparse  de  esto.  Si  fallara  y  no  puede  saber  el  motivo,  vea  la  seccion  de 
Problemas 


Probando 

Si  ha  construfdo  el  PHP  como  un  programa  CGI,  puede  probar  su  funcionamiento  tecleando  make  test. 
Siempre  es  buena  idea  probar  su  construccion.  Asf  puede  atrapar  pronto  los  problemas  del  PHP  en  su 
plataforma  sin  tener  que  batallar  con  ellos  luego. 


Comprobando  la  velocidad 

Si  ha  construfdo  el  PHP  como  un  programa  CGI,  puede  comprobar  la  velocidad  de  su  codigo  escribiendo 
make  bench.  Notese  que  se  el  modo  seguro  esta  habilitado  por  defecto,  el  test  no  podra  finalizar  si  se 
toma  mas  de  los  30  segundos  disponibles.  Esto  se  debe  a  que  la  funcion  set_time_limit')  no  se  puede 
usar  en  modo  seguro.  Use  el  ajuste  de  configuracion  max_execution_time  para  controlar  este  tiempo  en 
sus  propios  script,  make  bench  ignora  el  archivo  de  configuracion 


Instalacion  en  sistemas  Windows  95/98/NT 


Esta  gufa  de  instalacion  le  ayudara  a  instalar  y  configurar  el  PHP  en  sus  servidores  web  bajo  Windows 
9x/NT.  Esta  gufa  fue  compilada  por  Bob  Silva  (mailto:bob_silva@mail.umesd.kl2.or.us).  La  ultima 
revision  puede  encontrarse  en  http://www.umesd.kl2.or.us/php/win32install.html. 

Esta  gufa  proporciona  soporte  de  instalacion  para: 

•  Personal  Web  Server  (se  recomienda  la  ultima  version) 

•  Internet  Information  Server  3  6  4 

•  Apache  1.3.x 

•  Omni  HTTPd  2.0b  1 


15 


Pasos  Generales  de  Instalacion 


Capitulo  2.  Instalacion 


Los  siguientes  pasos  deben  realizarse  en  todas  las  instalaciones  antes  de  las  instrucciones  especfficas  de 
cada  servidor. 


•  Extraiga  el  archivo  de  distribucion  a  un  directorio  de  su  eleccion.  "C:\PHP3\"  es  un  buen  comienzo. 

•  Copie  el  archivo  ’php3.ini-dist’  a  su  directorio  ’%WINDOWS%’  y  renombrelo  a  ’php3.ini’.  Su 

directorio  ’%WINDOWS%’  es  tfpicamente: 

c:\windows  para  Windows  95/98 

c:\winnt  o  c:\winnt40  para  servidores  NT 

•  Edite  su  archivo  ’php3.ini’: 

•  Necesitaa  cambiar  la  opcion  ’extension_dir’  para  que  apunte  a  su  php-install-dir,  o  a  donde  quiera 
que  haya  puesto  sus  archivos  ’php3_*.dH\  P.ej.:  c:\php3 

•  Si  esta  utilizando  Omni  Httpd,  no  siga  el  siguiente  paso.  Fije  el  ’doc_root’  para  que  apunte  a  la  raiz 
web  de  sus  servidores.  P.ej.:  c:\apache\htdocs  o  c:\webroot 

•  Elija  que  modulos  desearfa  cargar  cuando  comience  el  PHP.  Puede  descomentar  las  lfneas: 
’extension=php3_*.dir  para  cargar  estos  modulos.  Algunos  modulos  requieren  que  tenga  instaladas 
en  sus  sistema  librerfas  adicionales  para  que  el  modulo  funcione  correctamente.  El  FAQ 
(http://www.php.net/FAQ.php)  de  PHP  tiene  mas  informacion  sobre  donde  obtener  librerfas  de 
soporte.  Tambien  puede  cargar  un  modulo  dinamicamente  en  su  script  utilizando:  dl("php_*.dll"); 

•  En  el  PWS  y  el  IIS  puede  fijar  el  browscap.ini  para  que  apunte  a: 
’c:\windows\system\inetsrv\browscap.ini’  bajo  Windows  95/98  y  a 
’c:\winnt\system32\inetsrv\browscap.ini’  bajo  NT  Server. 


Las  DLL  para  las  extensiones  del  PHP  van  precedidas  de  ’php3_’.  Esto  evita  confusiones  entre  las 
extensiones  del  PHP  y  sus  librerfas  de  soporte. 


Windows  95/98/NT  y  PWS/IIS  3 

El  metodo  recomendado  para  configurar  estos  servidores  es  usar  el  archivo  INF  inclufdo  con  la 
distribucion  (php_iis_reg.inf).  Quizas  desee  editar  este  archivo  y  asegurarse  que  las  extensiones  y 
directorios  de  instalacion  se  ajustan  a  su  configuracion.  O  puede  seguir  los  pasos  que  siguen  para  hacerlo 
de  forma  manual. 

AVISO:  Estos  pasos  conllevan  el  trabajar  directamente  con  el  registro  de  windows.  Un  error  aquf  puede 
dejar  su  sistema  en  un  estado  inestable.  Le  recomendamos  encarecidamente  que  haga  una  copia  de 
seguridad  del  registro  con  antelacion.  El  equipo  de  Desarrollo  del  PHP  no  se  hara  responsable  si  se  dana 
su  registro. 


•  Ejecute  Regedit. 

•  Navegue hasta:  HKEY_LOCAL_MACHINE  /System  /CurrentControlSet  /Services  /W3Svc 
/Parameters  /ScriptMap. 

•  En  el  menu  de  edicion  elija:  New->string  Value. 
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•  Escriba  la  extension  que  desea  usar  para  sus  script  PHP.  P.ej.:  ,php3 

•  Haga  doble  click  en  el  nuevo  valor  de  cadena  y  escriba  la  ruta  al  php .  exe  en  el  campo  del  valor.  P.ej.: 
c :  \php3\php .  exe  %s  %s.  La  parte  ’%s  %s’  son  MUY  importantes,  pues  el  PHP  no  funcionara 
correctamente  sin  ella. 

•  Repita  estos  pasos  para  cada  extension  que  desee  asociar  con  los  scripts  PHP. 

•  Ahora  navegue  hasta:  hkey_CLASSES_ROOT 

•  En  el  menu  de  edicion  elija:  New->Key. 

•  Dele  a  la  clave  el  nombre  de  la  extension  que  prepare  en  la  seccion  anterior.  P.ej.:  .  php 3 

•  Marque  la  nueva  clave  y  en  el  panel  del  lado  derecho  haga  doble  click  en  "default  value"  y  escriba 

phpf ile. 

•  Repita  el  ultimo  paso  para  cada  extension  que  haya  preparado  en  la  seccion  previa. 

•  Ahora  cree  otra  New->Key  bajo  hkey_CLASSES_ROOT  y  denommela  phpfile. 

•  Marque  la  nueva  clave  phpfile  y  haga  doble  click  en  el  panel  derecho  sobre  "default  value"  y 
escriba  php  Script. 

•  Pulse  el  boton  derecho  sobre  la  clave  phpfile  y  seleccione  New->Key  y  llamela  Shell. 

•  Pulse  el  boton  derecho  sobre  la  clave  Shell  y  elija  New->Key  y  llamela  open. 

•  Pulse  el  boton  derecho  sobre  la  clave  open  y  elija  New->Key  y  llamela  command. 

•  Marque  la  nueva  clave  command  y  en  el  panel  derecho  haga  doble  click  sobre  "default  value"  y  entre 

la  ruta  hasta  el  php .  exe.  P.ej.:  c :  \php3\php .  exe  -q  %1.  (no  olvide  el  %1). 

•  Saiga  del  Regedit. 


Los  usuarios  de  PWS  e  IIS3  tienen  ahora  un  sistema  completamente  operativo.  Los  usuarios  del  IIS3 
tambien  pueden  usar  una  curiosa  herramienta  (http://www.genusa.com/iis/iiscfg.html)  de  Steven  Genusa 
para  configurar  sus  mapeados  de  script. 


Windows  NT  e  IIS  4 


Para  instalar  el  PHP  en  un  NT  Server  con  IIS  4,  siga  estas  instrucciones: 


•  En  el  Controlador  de  Servicios  de  Internet  (MMC),  elija  el  sitio  Web  o  el  directorio  de  comienzo  de 
una  aplicacion. 

•  Abra  las  propiedades  del  directorio  (haciendo  click  derecho  y  eligiendo  propiedades)  y  luego  pulse 
sobre  la  pestana  Carpeta  Inicial,  Directorio  Virtual  o  Directorio. 

•  Pulse  el  boton  Configuracion  y  luego  pulse  sobre  la  pestana  Mapas  de  Aplicacion. 

•  Pulse  en  Anadir,  y  en  la  caja  Programa,  escriba:  c :  \path-to-php-dir\php .  exe  %s  %s.  DEBE 
mantene  los  %s  %s  al  final,  pues  el  PHP  no  funcionara  correctamente  si  se  equivoca  al  hacerlo. 

•  En  la  caja  Extension,  escriba  la  extension  de  fichero  que  desea  asociar  a  los  script  de  PHP.  Debe 
repetir  los  pasos  5  y  6  para  cada  extension  que  desee  asociar  con  los  scripts  PHP  (  .  php  3  y  .  phtml 
son  habituales). 
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•  Ajuste  la  seguridad  apropiada  (esto  se  realiza  en  el  Controlador  de  Servicio  de  Internet  (ISM)),  y  si  su 
NT  Server  usa  el  sistema  de  archivos  NTFS,  anada  derechos  de  ejecucion  para  I_USR_  al  directorio 
que  contenga  el  php  .  exe. 


Windows  9x/NT  y  Apache  1.3.x 

Debe  editar  sus  archivos  srm.conf  o  httpd.  conf  para  configurar  el  Apache  para  que  trabaje  con  el 
ejecutable  CGI  del  PHP. 

Aunque  puede  haber  algunas  variaciones  al  configurar  PHP  bajo  Apache,  esta  es  lo  suhcientemente 
simple  para  ser  usada  por  el  novato.  Por  favor,  consulte  la  Documentacion  del  Apache  para  saber  de  las 
subsiguientes  directivas  de  configuracion. 

•  ScriptAlias  /php3/  "c : /ruta-al-dir-del-php/ " 

•  AddType  application/x-httpd-php3  .php3 

•  AddType  application/x-httpd-php3  . phtml 

•  Action  application/x-httpd-php3  " /php3/php . exe " 


Para  utilizar  la  capacidad  de  marcado  del  codigo  fuente,  cree  simplemente  un  script  de  PHP  y  pegue  este 
codigo  en  el:  <?php  show_source  (  "  script_original_php  .  php3  "  )  ;  ?>.  Sustituya 
scr ipt_or iginal_php .  php3  por  el  nombre  del  archivo  del  que  desea  visualizar  el  codigo  fuente  (esta 
es  la  linica  forma  de  hacerlo).  Nat  a:  Bajo  Win-Apache  todas  las  barras  invertidas  de  una  mta  tal  como: 
"c:\directory\hle.ext",  deben  ser  convertidas  a  barras  hacia  adelante. 


Omni  HTTPd  2.0b1  para  Windows 

Esta  ha  resultado  ser  la  configuracion  mas  sencilla: 

Paso  1 :  Instale  el  servidor  Omni 

Paso  2:  Pulse  el  boton  derecho  sobre  el  icono  azul  del  OmniHTTPd  que  esta  en  la  barrita  del  sistema  y  elija  Propiedades 
Paso  3:  Pulse  sobre  Web  Server  Global  Settings 

Paso  4:  En  la  pestana ’External’,  escriba:  virtual  =  .php3  I  actual  =  c:\ruta-al-dir-del-php\php.exe 
Paso  5:  En  la  pestana  Mime,  escriba:  virtual  =  wwwserver/stdcgi  I  actual  =  .php3 
Paso  6:  Pulse  en  OK 

Repita  los  pasos  2  a  6  para  cada  extension  que  desee  asociar  al  PHP 


Modulos  del  PHP 


Tabla  2-1.  Modulos  del  PHP 


php3_c  alendar.  dll 


Funciones  de  conversion  de  calendario 
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php3 crypt.dll 

Funciones  de  criptograffa 

php3 dbase.dll 

Funciones  para  DBase 

php3 dbm.dll 

Emulacion  GDBM  con  la  librerfa  Berkeley  DB2 

php3 filepro.dll 

Acceso  SOLO  LECTURA  a  bases  de  datos  filepro 

php3 gd.dll 

Funciones  de  librerfa  GD  para  manipular  GIF 

php3 hyperwave.dll 

Funciones  de  HyperWave 

php3 imap4r2.dll 

Funciones  de  IMAP  4 

php3 ldap.dll 

Funciones  de  LDAP 

php3 msqll.dll 

Cliente  de  mSQL  1 

php3 msql2.dll 

Cliente  de  mSQL  2 

php3_mssql.dll 

Cliente  de  MS  SQL  client  (requiere  las  librerfas  de 
MSSQL  DB 

php3 mysql.dll 

Funciones  de  MySQL 

php3 nsmail.dll 

Funciones  de  correo  de  Netscape 

php3 oci73.dll 

Funciones  de  Oracle 

php3 snmp.dll 

Funciones  get  y  walk  de  SNMP  (jsolo  en  NT!) 

php3_zlib.dll 

Funciones  de  ZLib 

<?,Problemas? 

Lea  las  PMF  (FAQ) 

Algunos  problemas  son  mas  comunes  que  otros.  Los  mas  comunes  estan  listados  en  las  PMF  (Preguntas 
Mas  Frecuentes)  del  PHP,  que  estan  en  http://www.php.net/FAQ.php 


Informes  de  error 

Si  cree  que  ha  encontrado  un  error  en  el  PHP,  por  favor  informenos.  Los  desarrolladores  del  PHP 
probablemente  no  tengan  conocimiento  del  mismo,  y  salvo  si  informa  del  mismo,  pocas  probabilidades 
habra  de  que  lo  solucionen.  Puede  informar  de  los  errores  usando  el  sistema  de  rastreo  de  errores  en 
http://bugs.php.net/. 


Otros  problemas 

Si  aun  se  encuentra  atascado,  alguien  de  la  lista  de  correos  del  PHP  puede  ser  capaz  de  ayudarle.  Debera 
buscar  primero  en  los  archivos,  por  si  acaso  alguien  ya  ha  respondido  a  otra  persona  que  tuvo  el  mismo 
problema  que  usted.  Los  archivos  estan  disponibles  desde  la  pagina  de  soporte  en  http://www.php.net/. 
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Para  suscribirse  a  la  lista  de  correo  de  PHP,  envfe  un  correo  vaclo  a  php-general-subscribe@lists.php.net 
(mailto:php-general-subscribe@lists.php.net).  La  direccion  de  la  lista  de  correo  es 

php-general@ lists . php . net. 

Si  desea  ayuda  sobre  la  lista  de  correo,  intente  ser  preciso  y  de  los  detalles  necesarios  sobre  su  entorno 
(que  sistema  operativo,  que  version  de  PHP,  que  servidor  web,  si  esta  ejecutando  el  PHP  como  CGI  o 
como  modulo  de  servidor,  etc.)  y  tambien  codigo  suficiente  para  que  otros  puedan  reproducir  y 
comprobar  su  problema. 
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El  archivo  de  configuracion 

El  archivo  de  configuracion  (llamado  php3  .  ini  en  PHP  3.0,  y  simplemente  php .  ini  a  partir  del  PHP 
4.0)  es  lefdo  cuando  arranca  el  PHP.  Para  las  versiones  de  PHP  como  modulo  de  servidor  esto  solo  ocurre 
una  vez  al  arrancar  el  servidor  web.  Para  la  version  CGI,  esto  ocurre  en  cada  llamada. 

Cuando  se  utiliza  PHP  como  modulo  Apache,  tambien  puede  cambiar  los  ajustes  de  configuracion 
utilizando  directivas  en  los  archivos  de  configuracion  del  Apache  y  en  los  .htaccess. 

Con  el  PHP  3.0  hay  directivas  Apache  que  se  corresponden  a  cada  uno  de  los  ajustes  de  configuracion 
del  php3  .  ini,  con  la  excepcion  que  su  nombre  va  precedido  de  "php3_". 

Con  el  PHP  4.0  solo  hay  unas  pocas  directivas  de  Apache  que  le  permiten  cambiar  los  ajustes  de 
configuracion  del  PHP. 

php_value  nombre  valor 

Fija  el  valor  de  la  variable  especificada. 

php_flag  nombre  on  /  off 

Fija  una  opcion  de  configuracion  de  tipo  Boolean. 

php_admin_value  nombre  valor 

Fija  el  valor  de  la  variable  especificada.  Los  ajustes  de  configuracion  de  tipo  "Admin"  solo  se 
pueden  fijar  desde  los  archivos  principales  de  configuracion  del  Apache,  y  no  desde  los  .htaccess. 

php_admin_flag  nombre  on  /  off 

Fija  una  opcion  de  configuracion  de  tipo  Boolean. 


Puede  ver  los  ajustes  de  los  valores  de  configuracion  en  la  salida  de  phpinfoO-  Tambien  puede  acceder  a 
los  valores  individuales  de  los  ajustes  de  configuracion  utilizando  get_cfg_var'). 


Directivas  Generales  de  Configuracion 


a sp_ tags  boolean 

Permite  el  uso  de  las  etiquetas  estilo  ASP  <%  %>  ademas  de  las  habituales  etiquetas  <?php  ?>. 
Tambien  se  incluye  el  atajo  para  imprimir  variables  <%=  $valor  %>.  Para  mas  informacion,  vea 
Escapando  del  HTML 

Nota:  El  soporte  para  etiquetas  estilo  ASP  se  anadio  en  la  3.0.4. 
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auto_append_file  string 

Especifica  el  nombre  de  un  archivo  que  es  troceado  automaticamente  despues  del  archivo  principal. 
El  archivo  se  incluye  como  si  fuese  llamado  mediante  la  funcion  include  [),  asf  que  se  utiliza 
include_path 

El  valor  especial  none  desconecta  la  adicion  automatica  de  archivos. 

Nota:  Si  el  script  es  terminado  con  exit;),  no  tendra  lugar  la  adicion  automatica. 


aut o_prepen d_file  string 

Especifica  el  nombre  de  un  archivo  que  es  troceado  automaticamente  antes  del  archivo  principal. 
Specifies  the  name  of  a  file  that  is  automatically  parsed  before  the  main  file.  El  archivo  se  incluye 
como  si  fuese  llamado  mediante  la  funcion  include  3,  asf  que  se  utiliza  include_path 

El  valor  especial  none  desconecta  la  adicion  automatica  de  archivos. 


cgi_ext  string 


display_errors  boolean 

Determina  si  los  errores  se  visualizan  en  pantalla  como  parte  de  la  salida  en  HTML  o  no. 
doc_root  string 

"Directorio  raiz"  del  PHP  en  el  servidor.  Solo  se  usa  si  no  esta  vacfo.  Si  el  PHP  se  configura  con 
safe  mode  no  se  sirven  archivos  fuera  de  este  directorio. 

engine  boolean 

Esta  directiva  solo  es  realmente  util  en  la  version  de  PHP  como  modulo  Apache.  Se  utiliza  por 
sitios  que  desean  habilitar  la  ejecucion  del  PHP  directorio  por  directorio  o  en  base  a  cada  servidor 
virtual.  Poniendo  php3_engine  off  en  los  sitios  apropiados  del  archivo  httpd.  conf,  se  puede 
habilitar  o  deshabilitar  el  PHP. 

error_log  string 

Nombre  del  fichero  para  registrar  los  errores  de  un  script.  Si  se  utiliza  el  valor  especial  syslog,  los 
errores  se  envfan  al  registro  de  errores  del  sistema.  En  UNIX  se  refiere  a  syslog(3)  y  en  Windows 
NT  al  registro  de  eventos.  El  registro  de  errores  del  sistema  no  es  soportado  bajo  Windows  95. 
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error_reporting  integer 

Fija  el  nivel  de  informe  de  errores.  El  parametro  es  un  entero  que  representa  un  campo  de  bits. 
Sume  los  valores  de  los  niveles  de  informe  de  error  que  desea. 

Tabla  3-1.  Niveles  de  Informe  de  Errores 


valor  de  bit 

informe  habilitado 

1 

errores  normales 

2 

avisos  normales 

4 

errores  del  troceador  (parser) 

8 

avisos  de  estilo  no  crfticos 

El  valor  por  defecto  para  esta  directiva  es  7  (se  muestran  los  errores  normales,  avisos  normales  y 
errores  de  parser). 

open_basedir  string 

Limita  los  archivos  que  se  pueden  abrir  por  el  PHP  al  arbol  de  directorios  especificado. 

Cuando  un  script  intenta  abrir  un  archivo  con,  por  ejemplo,  fopen  o  gzopen,  se  comprueba  su 
localization.  Si  el  fichero  esta  fuera  del  arbol  de  directorios  especificado,  PHP  se  negara  a  abrirlo. 
Todos  los  enlaces  simbolicos  son  resueltos,  de  modo  que  no  es  posible  evitar  esta  limitation  usando 
uno  de  ellos. 

El  valor  especial .  indica  que  el  directorio  base  sera  aquel  en  el  que  reside  el  script. 

Bajo  Windows,  separe  los  directorios  mediante  punto  y  coma.  En  el  resto  de  sistemas,  separelos  con 
dos  puntos  Como  modulo  de  Apache,  los  senderos  para  open_basedir  de  los  directorios  padre  se 
heredan  ahora  automaticamente. 

Nota:  El  soporte  para  directorios  multiples  se  anadio  en  la  3.0.7. 


El  valor  por  defecto  es  permitir  abrir  todos  los  archivos. 


gpc_order  string 

Fija  el  order  de  troceo  de  variables  GET/POST/COOKIE.  El  valor  por  defecto  de  esta  directiva  es 
"GPC".  Fijandola,  por  ejemplo,  a  "GP",  hara  que  el  PHP  ignore  por  completo  las  cookies  y  que 
sobreescriba  las  variables  recibidas  por  GET  con  las  que  tengan  el  mismo  nombre  y  vengan  por 
POST. 

ignore_user_abort  string 

Por  defecto  esta  a  on.  Si  se  cambia  a  off,  los  script  terminaran  tan  pronto  como  intenten  enviar  algo 
despues  de  que  un  cliente  ha  roto  la  conexion.  ignore_user_abort  3. 

include_path  string 

Especifica  una  lista  de  directorios  en  los  que  las  funciones  require  '),  include  3  y 
fopen_with_path( )  buscan  los  archivos.  El  formato  es  similar  a  la  variable  de  entorno  de  sistema 
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PATH:  una  lista  de  directories  separados  por  dos  puntos  en  UNIX  o  por  punto  y  coma  en  Windows. 
Ejemplo  3-1.  include_path  en  UNIX 

include  path= . : /home/httpd/php-lib 

Ejemplo  3-2.  include_path  en  Windows 

include_path=" . ; c : \www\phplib" 

El  valor  por  defecto  para  esta  directiva  es  .  (solo  el  directorio  actual). 
isapi_ext  string 


log_errors  boolean 

Dice  si  los  mensajes  de  error  de  los  script  deben  ser  registrados  o  no  en  el  registro  del  servidor.  Esta 
opcion,  por  tanto,  es  especffica  del  mismo. 

magic_quotes_gpc  boolean 

Fija  el  estado  magic_quotes  para  operaciones  GPC  (Get/Post/Cookie).  Si  magic_quotes  vale  on, 
todas  las  ’  (comilla  sencilla), "  (comilla  doble),  \  (barra  invertida)  y  los  NUL  son  automaticamente 
marcados  con  una  barra  invertida.  Si  ademas  magic_quotes_sybase  vale  on,  la  comilla  sencilla  es 
marcada  con  otra  comilla  sencilla  en  lugar  de  la  barra  invertida. 

magic_quotes_runtime  boolean 

Si  se  habilita  magic_quotes_runtime,  muchas  de  las  funciones  que  devuelven  datos  de  algun 
tipo  de  fuente  externa  incluyendo  bases  de  datos  y  archivos  de  texto  devolveran  las  comillas 
marcadas  con  una  barra  invertida.  Si  tambien  esta  activo  magic_quotes_sybase ,  la  comilla 
simple  es  marcada  con  una  comilla  simple  en  lugar  de  la  barra  invertida. 

magic_quotes_sybase  boolean 

Si  magic_quotes_sybase  esta  a  on,  la  comilla  simple  es  marcada  con  una  comilla  simple  en 
lugar  de  la  barra  invertida  cuando  estan  habilitados  magic_quotes_gpc  o 
magic_quotes_runtime. 

max_execution_time  integer 

Fija  el  tiempo  maximo  en  segundos  que  se  le  permite  usar  a  un  script  antes  de  ser  finalizado  por  el 
interprete.  As!  se  evita  que  scripts  mal  escritos  puedan  bloquear  el  servidor. 

memory_limit  integer 

Fija  el  tamano  maximo  de  memoria  en  bytes  que  se  permite  reclamar  a  un  script.  Asf  se  evita  que 
script  mal  escritos  se  coman  toda  la  memoria  dispomible  de  un  servidor. 

nsapi_ext  string 
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short_open_tag  boolean 

Indica  si  se  debe  permitir  el  formato  corto  (<?  ?>)  de  la  etiqueta  de  apertura  del  PHP.  Si  desea 
utilizar  PHP  en  combination  con  XML,  debera  desactivar  esta  opcion.  Si  esta  desactivada,  debera 
utilizar  el  formato  largo  de  la  etiqueta  de  apertura  (<?php  ?>). 

sql .  safe_mode  boolean 


track_errors  boolean 

Si  esta  habilitada,  el  ultimo  mensaje  de  error  estara  siempre  presente  en  la  variable  global 
$php_errormsg. 

t rack_vars  boolean 

Si  esta  activada,  la  information  de  entrada  de  GET,  POST  y  de  las  cookies  se  puede  encontrar  en 
las  matrices  asociativas  $HTTP_GET_VARS,$HTTP_POST_VARS  y  $HTTP_COOKIE_VARS 
respectivamente. 

upload_tmp_dir  string 

El  directorio  temporal  utilizado  para  almacenar  archivos  cuando  se  envfan  al  servidor.  Debe  tener 
permiso  de  escritura  para  el  usuario  bajo  el  que  corra  el  PHP. 

user_dir  string 

El  nombre  base  del  directorio  utilizado  bajo  el  directorio  inicial  de  un  usuario  para  los  archivos 
PHP  Por  ejemplo:  paginas_html. 

warn_pl  us_overl  oading  boolean 

Si  esta  activada,  esta  opcion  hace  que  el  PHP  muestre  un  aviso  cuando  el  operador  suma  (+)  se 
utiliza  en  cadenas.  Asf  es  mas  facil  encontrar  scripts  que  necesitan  ser  reescritos  utilizando  en  su 
lugar  el  concatenador  de  cadenas  ( . ). 


Directivas  de  Configuracion  de  Correo 

SMTP  string 

Nombre  DNS  o  direccion  IP  del  servidor  de  SMTP  que  el  PHP  bajo  Windows  debera  usar  para 
enviar  correo  con  la  funcion  mail'). 

sendmail_from  string 

La  direccion  del  remitente  ("De : ")  para  los  correos  enviados  desde  PHP  bajo  Windows. 

sendmail_path  string 

Localization  del  programa  sendmail.  Generalmente  /usr/sbin/sendmail  o 
/usr/lib/ sendmail.  configure  intenta  localizarle  este  archivo  lo  mejor  que  puede  y  fijar  un 
valor  por  defecto,  pero  en  caso  de  fallo,  lo  puede  usted  fijar  aquf. 
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Los  sistemas  que  no  usan  sendmail  deberan  fijar  esta  directiva  al  nombre  del  programa  alternativo 
que  ofrezca  su  sistema  de  correo,  si  es  que  existe.  Por  ejemplo,  los  usuarios  del  Qmail 
(http://www.qmail.org/)  pueden  fijarlo  normalmente  a  /var/qmail/bin/sendmail. 


Directivas  de  Configuracion  de  Modo  Seguro 

safe_mode  boolean 

Para  activar  el  modo  seguro  del  PHP  Lea  el  Capitulo  de  seguridad  para  mas  informacion. 

safe_mode_exec_dir  string 

Si  el  PHP  se  utiliza  en  modo  seguro,  la  funcion  system/)  y  el  resto  de  funciones  que  ejecutan 
programas  del  sistema  se  niegan  a  ejecutar  programas  que  no  esten  en  este  directorio. 

Directivas  de  Configuracion  del  Debugger 

debugger .  host  string 

Nombre  DNS  o  direction  IP  del  servidor  usado  por  el  debugger. 

debugger .  port  string 

Numero  de  puerto  usado  por  el  debugger. 

debugger .  enabled  boolean 

Indica  si  el  debugger  esta  habilitado  o  no. 


Directivas  de  Carga  de  Extensiones 

enable_dl  boolean 

Esta  directiva  solo  es  util  en  la  version  del  PHP  como  modulo  del  Apache.  Puede  habilitar  o 
deshabilitar  para  un  servidor  virtual  o  para  un  directorio  la  carga  dinamica  de  extensiones  de  PHP 
mediante  dl(). 

La  razon  principal  para  deshabilitar  la  carga  dinamica  es  la  seguridad.  Con  la  carga  dinamica  es 
posible  ignorar  las  restricciones  safe_mode  y  open_basedir. 

El  valor  por  defecto  es  permitir  la  carga  dinamica,  excepto  cuando  se  usa  el  modo  seguro.  En  modo 
seguro,  siempre  es  imposible  usar  dl(). 


extension_dir  string 

En  que  directorio  debe  buscar  el  PHP  las  extensiones  cargables  dinamicamente. 
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extension  string 

Que  extensiones  dinamicas  debe  cargar  el  PHP  cuando  arranca. 

Directivas  de  Configuracion  de  MySQL 

mysql .  allow_persistent  boolean 

Si  permitir  o  no  conexiones  MySQL  persistentes. 

mysql .  default_host  string 

El  servidor  por  defecto  para  utilizar  cuando  se  conecte  al  servidor  de  bases  de  datos  si  no  se 
especifica  otro  distinto. 

mysql .  default_user  string 

El  nombre  de  usuario  por  defecto  para  utilizar  cuando  se  conecta  al  servidor  de  base  de  datos  si  no 
se  especifica  otro. 

mysql .  default_password  string 

La  clave  por  defecto  para  utilizar  cuando  se  conecta  al  servidor  de  base  de  datos  si  no  se  especifica 
otro. 

mysql  ,max_persistent  integer 

El  numero  maximo  de  conexiones  persistentes  de  MySQL  por  proceso. 

mysql .  max_links  integer 

El  numero  maximo  de  conexiones  de  MySQL  por  proceso,  incluyendo  las  persistentes. 

Directivas  de  Configuracion  de  mSQL 

msql .  allow_persistent  boolean 

Si  se  permiten  o  no  conexiones  persistentes  de  mSQL. 

msql  ,max_persistent  integer 

El  numero  maximo  de  conexiones  persistentes  mSQL  por  proceso. 

msql  ,max_links  integer 

El  numero  maximo  de  conexiones  de  mSQL  por  proceso,  incluyendo  las  persistentes. 
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pgsql .  allow_persistent  boolean 

Si  se  permiten  o  no  conexiones  persistentes  de  Postgres. 

pgsql  ,max_persistent  integer 

El  numero  maximo  de  conexiones  persistentes  Postgres  por  proceso. 

pgsql  ,max_links  integer 

El  numero  maximo  de  conexiones  de  Postgres  por  proceso,  incluyendo  las  persistentes. 


SESAM  Configuration  Directives 

sesam_oml  string 

Name  of  BS2000  PLAM  library  containing  the  loadable  SESAM  driver  modules.  Required  for 
using  SESAM  functions.  The  BS2000  PLAM  library  must  be  set  ACCESS=READ,SHARE=YES 
because  it  must  be  readable  by  the  apache  server’s  user  id. 

sesam_con  fig  file  string 

Name  of  SESAM  application  configuration  file.  Required  for  using  SESAM  functions.  The 
BS2000  file  must  be  readable  by  the  apache  server’s  user  id. 

The  application  configuration  file  will  usually  contain  a  configuration  like  (see  SESAM  reference 
manual): 


CNF=B 

NAM=K 

NOTYPE 


sesam_messagecatalog  string 

Name  of  SESAM  message  catalog  file.  In  most  cases,  this  directive  is  not  neccessary.  Only  if  the 
SESAM  message  file  is  not  installed  in  the  system’s  BS2000  message  file  table,  it  can  be  set  with 
this  directive. 

The  message  catalog  must  be  set  ACCESS=R£AD,SHARE=YES  because  it  must  be  readable  by 
the  apache  server’s  user  id. 
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Sybase .  allow_persistent  boolean 

Si  se  permiten  o  no  conexiones  persistentes  de  Sybase. 

Sybase  ,max_persistent  integer 

El  numero  maximo  de  conexiones  persistentes  Sybase  por  proceso. 

Sybase  ,max_l inks  integer 

El  numero  maximo  de  conexiones  de  Sybase  por  proceso,  incluyendo  las  persistentes. 


Directivas  de  Configuracion  de  Sybase-CT 

sybct .  allow_persistent  boolean 

Si  se  permiten  o  no  conexiones  persistentes  de  Sybase-CT.  El  valor  por  defecto  es  on. 

sybct  ,max_persistent  integer 

El  numero  maximo  de  conexiones  persistentes  Sybase-CT  por  proceso.  El  valor  por  defecto  es  -1, 
que  significa  ilimitadas. 

sybct .  max_links  integer 

El  numero  maximo  de  conexiones  de  Sybase-CT  por  proceso,  incluyendo  las  persistentes.  El  valor 
por  defecto  es  -1,  que  significa  ilimitadas. 

sybct  ,min_server_severity  integer 

Los  mensajes  de  servidor  con  gravedad  mayor  o  igual  que  sybct  .min_server_severity 
seran  reportados  como  avisos.  Este  valor  tambien  se  puede  cambiar  desde  un  script  usando  la 
funcion  sybase_min_server_severity().  El  valor  por  defecto  es  10,  que  reporta  los  errores  de 
informacion  con  gravedad  o  mayores. 

sybct  .min_client_severity  integer 

Los  mensajes  de  librerfa  de  cliente  con  gravedad  mayor  o  igual  que 

sybct . m±n_client_severity  seran  reportados  como  avisos.  Este  valor  tambien  se  puede 
cambiar  desde  un  script  usando  la  funcion  sybase_min_client_severity().  El  valor  por  defecto  es 
10,  que  desconecta  los  avisos. 

sybct .  login_timeout  integer 

El  numero  maximo  de  segundos  de  espera  por  un  intento  de  conexion  con  exito  antes  de  indicar  un 
fallo.  Notese  que  si  se  ha  excedido  max_execut ion_t ime  cuando  finaliza  la  espera  de  un 
intento  de  conexion,  el  script  sera  finalizado  antes  de  que  se  pueda  tomar  una  action  en  caso  de 
fallo.  El  valor  por  defecto  es  1  minuto. 
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sybct .  timeout  integer 

El  numero  maximo  de  segundos  de  espera  por  una  operation  de  consulta  o  select_db  con  exito 
antes  de  indicar  un  fallo.  Notese  que  si  se  ha  excedido  max_execution_time  cuando  finaliza  la 
espera  de  un  intento  de  conexion,  el  script  sera  finalizado  antes  de  que  se  pueda  tomar  una  action  en 
caso  de  fallo.  El  valor  por  defecto  es  sin  lfmite. 

sybct .  hostname  string 

El  nombre  de  la  maquina  desde  la  que  dice  estarse  conectando,  para  que  se  visualize  con  sp_who(). 
El  valor  por  defecto  es  "none". 


Directivas  de  Configuracion  de  Informix 

ifx.  allow_persistent  boolean 

Si  se  permiten  o  no  conexiones  persistentes  de  Informix. 

ifx.max_persistent  integer 

El  numero  maximo  de  conexiones  persistentes  de  Informix  por  proceso. 

ifx.max_links  integer 

El  numero  maximo  de  conexiones  Informix  por  proceso,  incluyendo  las  persistentes. 

ifx.  default_host  string 

El  servidor  por  defecto  al  que  conectarse  si  no  se  especifica  uno  en  ifx_connectj  o  en 
ifxpconnect). 

ifx.  default_user  string 

El  id  de  usuario  por  defecto  para  utilizar  si  no  se  especifica  uno  en  ifx_connect')  o  en 
ifxpconnect'). 

ifx.  default_pas  sword  string 

La  clave  por  defecto  para  utilizar  si  no  se  especifica  uno  en  ifx_connect ')  o  en  ifx_pconncct). 

ifx. blob  infile  boolean 

Ffjelo  a  true  si  desea  recibir  las  columnas  blob  (objetos  binarios  grandes)  en  un  archivo,  y  a 
false  si  las  desea  en  memoria.  Puede  cambiar  el  ajuste  en  tiempo  de  ejecucion  utilizando 

ifx_blobinfile_mode  3. 

ifx.  t  ext  asvar  char  boolean 

Ffjelo  a  true  si  desea  recibir  las  columnas  TEXT  como  cadenas  normales  en  las  instrucciones 
select,  y  a  false  si  quiere  usar  parametros  de  identificador  de  blobs.  Puede  cambiar  el  ajuste  en 
tiempo  de  ejecucion  utilizando  ifx_textasvarchar\). 
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ifx.byteasvarchar  boolean 

Ffjelo  a  true  si  desea  devolver  las  columnas  BYTE  como  cadenas  normales  en  las  instrucciones 
select,  y  a  false  si  quiere  usar  parametros  de  identificador  de  blobs.  Puede  cambiar  el  ajuste  en 
tiempo  de  ejecucion  utilizando  ifx_byteasvarcharO. 

ifx.  char  asvar  char  boolean 

Ffjelo  a  true  si  desea  suprimir  los  espacios  a  la  derecha  de  las  columnas  CHAR  cuando  las  solicita. 

ifx .  null  format  boolean 

Ffjelo  a  true  si  desea  que  las  columnas  null  (nulas)  se  devuelvan  como  la  cadena  literal  "null", 
y  a  false  si  desea  que  se  devuelvan  como  la  cadena  vacfa  Puede  cambiar  el  ajuste  en  tiempo  de 
ejecucion  utilizando  ifx_nu  I  [format'). 

Directivas  de  Configuracion  de  Matematica  BC 

bcmath  .scale  integer 

Numero  de  dfgitos  decimales  para  todas  las  funciones  de  bcmath. 

Directivas  de  Configuracion  de  Capacidades  de  los  Navegadores 

browscap  string 

Nombre  del  archivo  de  capacidades  del  navegador.  Vea  tambien  get_browser'). 

Directivas  Unificadas  de  Configuracion  de  ODBC 

uodbc.  default_db  string 

Fuentes  de  datos  ODBC  a  utilizar  si  no  se  especifica  una  en  odbc_connectO  o  en  odbc_pconnect '). 

uodbc .  default_user  string 

Nombre  de  usuario  si  no  se  especifica  uno  en  odbc_connect')  o  en  odbc_pconnect'). 

uodbc.  default_pw  string 

Clave  para  usar  si  no  se  especifica  una  en  odbc_connectJ)  o  en  odbc_pconnectJ). 

uodbc .  allow_persistent  boolean 

Si  se  permiten  o  no  conexiones  persistentes  de  ODBC. 

uodbc .max_persistent  integer 

El  numero  maximo  de  conexiones  persistentes  de  ODBC  por  proceso. 


32 


Capitulo  3.  Configuration 


uodbc .  max_links  integer 

El  numero  maximo  de  conexiones  ODBC  por  proceso,  incluyendo  las  persistentes. 
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PHP  es  un  potente  lenguaje  y  el  interprete,  tanto  incluido  en  el  servidor  web  como  modulo  o  ejecutado 
como  un  binario  CGI,  puede  acceder  a  ficheros,  ejecutar  comandos  y  abrir  comunicaciones  de  red  en  el 
servidor.  Todas  estas  caracteristicas  hacen  que  lo  que  se  ejecute  en  el  servidor  web  sea  inseguro  por 
defecto.  PHP  ha  sido  disenado  especificamente,  para  ser  un  lenguaje  mas  seguro  para  escribir  programas 
CGI,  que  Perl  o  C  y  con  la  correcta  seleccion  de  las  opciones  de  configuracion  del  tiempo  de 
compilacion  y  ejecucion  se  consigue  la  exacta  combinacion  de  libertad  y  seguridad  que  se  necesita. 

Ya  que  existen  diferentes  modos  de  utilizar  PHP,  existen  multitud  de  opciones  de  configuracion  que 
permiten  controlar  su  funcionamiento.  Una  gran  seleccion  de  opciones  garantiza  que  se  pueda  usar  PHP 
para  diferentes  usos,  pero  tambien  significa  que  existen  combinaciones  de  estas  opciones  y 
configuraciones  del  servidor  que  producen  instalaciones  inseguras.  Este  capitulo  explica  las  diferentes 
combinaciones  de  opciones  de  configuracion  y  las  situaciones  donde  pueden  ser  usadas  de  manera 
segura. 


Binarios  CGI 

Posibles  ataques 

Usando  PHP  como  un  binario  CGI  es  una  opcion  para  instalaciones  que  por  cualquier  causa  no  quieren 
integral'  PHP  como  modulo  en  el  software  servidor  (p.ej:  Apache),  o  usaran  PHP  con  diferentes  clases  de 
CGI  wrappers  para  crear  entornos  chroot  y  setuid  seguros  para  los  scripts.  Esta  configuracion  implica 
generalmente  el  instalar  el  binario  ejecutable  de  PHP  en  el  directorio  cgi-bin  del  servidor  web.  El 
documento  del  CERT  CA-96.1 1 

(http://www.cert.org/advisories/CA-96T  l.interpreters_in_cgi_bin_dir.html)  recomienda  no  instalar 
interpretes  en  cgi-bin.  Aunque  el  binario  PHP  puede  ser  usado  como  interprete  independiente,  PHP  esta 
disenado  para  prevenir  los  ataques  que  esta  configuracion  hace  posible. 

•  Accediendo  a  ficheros  del  sistema:  http  :  //my .  host/ cgi-bin/php?/etc/passwd 

La  informacion  introducida  despues  del  signo  de  interrogation  (?)  es  transferida  como  argumento  de 
la  llnea  de  comando  al  interprete  por  el  interfaz  del  CGI.  Normalmente  los  interpretes  abren  y  ejecutan 
el  fichero  especificado  como  el  primer  argumento  en  la  llnea  de  comando. 

Cuando  se  ejecuta  como  un  CGI  script,  PHP  rechaza  interpretar  los  argumentos  de  la  llnea  de 
comando. 


•  Accediendo  cualquier  documento  web  en  el  servidor: 

http : //my . host /cgi-bin /php/ secret /doc . html 

La  informacion  con  el  camino  (path)  de  la  URL  despues  del  nombre  del  binario  PHP, 

/secret/doc .  html  es  usada  convencionalmente  para  especificar  el  nombre  del  fichero  que  sera 
abierto  e  interpretado  por  el  programa  CGI.  Normalmente,  algunas  directivas  del  servidor  web 
(Apache:Action)  son  usadas  para  redireccionar  peticiones  de  documentos  como 
http :  /  /my .  host /secret /script  ,php3  al  interprete  PHP.  Con  esta  configuracion,  el  servidor 
web  comprueba  primero  los  permisos  de  acceso  al  directorio  /secret,  y  despues  crea  la  peticion 
redireccionada  http :  //my .  host/cgi-bin/php/secret/script .  php3.  Desafortunadamente,  si 
la  peticion  es  hecha  de  esta  forma  en  un  principio,  el  servidor  web  no  comprueba  los  permisos  de 
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Caso 


Caso 


Caso 


acceso  del  fichero  /secret/script  ,php3,  sino  solamente  del  fichero  /cgi-bin/php.  De  esta 
manera  cualquier  usuario  que  pueda  acceder  /cgi-bin/php  tambien  puede  acceder  a  cualquier 
documento  protegido  en  el  servidor  web. 

En  PHP,  a  la  hora  de  compilar,  la  opcion  de  configuracion  —  enable-force-cgi-redirect  y  las  directivas 
de  configuracion  a  la  hora  de  ejecutar  doc_root  y  user_dir  pueden  ser  usadas  para  prevenir  este  ataque, 
si  el  arbol  de  documentos  del  servidor  tiene  cualquier  directorio  con  acceso  restringido.  Ver  mas 
adelante  la  explicacion  de  las  diferentes  combinaciones. 


:  solamente  se  sirven  ficheros  publicos 

Si  tu  servidor  no  contiene  informacion  que  este  protegida  con  clave  o  acceso  de  control  de  IPs,  no  se 
necesitan  estas  opciones  de  configuracion.  Si  tu  servidor  web  no  permite  realizar  redireccionamientos,  o 
el  servidor  no  tiene  modo  de  comunicar  al  binario  PHP  que  la  peticion  es  una  peticion  segura 
redireccionada,  podeis  especificar  la  opcion  —  disable-force-cgi-redirect  en  el  script  de  configuracion.  De 
todas  maneras,  teneis  que  aseguraros  que  vuestros  scripts  PHP  no  confien  en  la  manera  al  llamar  al 
script,  ni  de  forma  directa  http :  /  /my  .host /cgi-bin/php /dir /script  ,php3  o  por  redireccion 
http : / /my . host /dir /script . php3. 

Redireccionamiento  puede  ser  configurado  en  Apache  usando  las  directivas  AddHandler  y  Action  (ver 
mas  abajo). 


:  usando  --enable-force-cgi-redirect 

Esta  opcion  a  la  hora  de  compilar  previene  que  alguien  llame  PHP  directamente  con  una  url  como  la 
siguiente  http :  /  /my .  host /cgi-bin/php/  secret  dir/  script .  php3.  PHP  solamente  analizara  en 
este  modo  si  ha  pasado  por  una  regia  de  redireccionamiento  en  el  servidor. 

Normalmente  la  redireccion  en  la  configuracion  de  Apache  es  hecha  con  la  siguientes  directivas: 

Action  php3-script  /cgi-bin/php 
AddHandler  php3-script  .php3 


Esta  opcion  ha  sido  solo  comprobada  con  el  servidor  web  Apache,  y  depende  de  Apache  para  fijar  la 
variable  de  entorno  CGI  no  estandar  REDIRECT_STATUS  en  las  peticiones  de  redireccionamiento.  Si  tu 
servidor  web  no  soporta  ningun  modo  para  informar  si  una  peticion  es  directa  o  redireccionada,  no 
podeis  usar  esta  opcion  y  debereis  usar  alguno  de  los  otros  modos  de  ejecucion  de  la  version  CGI 
documentados  aqui. 


:  Usando  doc_root  or  user_dir 

Incluir  contenidos  activos,  como  script  y  ejecutables,  en  el  directorio  de  documentos  del  servidor  web,  es 
algunas  veces  considerada  una  practica  insegura.  Si  por  algun  fallo  de  configuracion,  los  scripts  no  son 
ejecutados  pero  mostrados  como  documentos  HTML,  cualquiera  podra  conseguir  codigo  registrado  o 
informacion  de  seguridad,  como  p.ej:  claves  de  acceso.  Por  ello,  muchos  administradores  prefieren 
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utilizar  otra  estructura  de  directories  que  contenga  solamente  los  scripts,  los  cuales  seran  solamente 
accesibles  via  PHP  CGI,  y  por  ello  siempre  seran  interpretados  y  no  mostrados. 

Habra  que  tener  en  cuenta  que  si  el  metodo  que  asegura  que  las  peticiones  no  son  redireccionadas,  como 
hemos  descrito  en  la  seccion  anterior,  no  esta  disponible,  sera  necesario  configurar  un  script  doc_root 
que  sea  diferente  del  "web  document  root". 

Podeis  definir  el  script  PHP  "document  root"  con  la  directiva  de  configuracion  doc_root  en  el  fichero  de 
configuracion  o  definir  la  variable  de  entorno  PHP_DOCUMENT_ROOT.  Si  esta  definida,  la  version 
CGI  de  PHP  siempre  obtendra  el  nombre  del  fichero  a  abrir  con  doc_root  y  el  camino  (path)  utilizado 
en  la  peticion,  asi  podeis  estar  seguros  que  ningun  script  sera  ejecutado  fuera  de  este  directorio  (excepto 
para  user_dir,  ver  a  continuacion) 

Otra  opcion  que  se  puede  usar  aqui  es  user_dir  Cuando  user_dir  no  esta  definido,  lo  unico  que  controla 
la  apertura  del  fichero  es  doc_root.  Si  intentamos  abrir  una  url  tal  como  esta 

http :  /  /my .  host /-user /doc  ,php3  no  se  abrira  un  fichero  en  el  directorio  de  usuarios,  en  su  lugar  se 
abrira  un  fichero  llamado  -user/doc  .php3  en  el  directorio  doc_root.  (si,  un  directorio  que  empieza  por 
tilde  [-]). 

Si  user_dir  esta  definido  por  ejemplo  como  public_php,  una  peticion  tal  como 
http :  /  /my .  host /-user /doc  ,php3,  abrira  un  fichero  llamado  doc  .php3  en  el  directorio  llamado 
public_php  del  directorio  "home"  del  usuario.  Si  el  directorio  del  usuario  es  /home/user,  el  fichero 
ejecutado  sera  /home/user/public_php/doc.php3. 

La  expansion  de  user_dir  ocurre  sin  tener  en  cuenta  la  configuracion  de  doc_root ,  de  este  modo  se 
puede  controlar  los  accesos  al  directorio  principal  (document  root)  y  al  directorio  de  usuario 
separadamente. 


Caso  4:  Analizador  PHP  fuera  del  arbol  web. 

Una  opcion  muy  segura  es  poner  el  analizador  binario  PHP,  en  algun  lugar  fuera  del  arbol  de  ficheros 
web.  Por  ejemplo  en  /usr/local/bin.  La  unica  pega  real  de  esta  opcion  es  que  habra  que  poner  una 
linea  similar  a: 

# ! /usr/local/bin/php 


como  primera  linea  en  cualquier  fichero  que  contenga  codigo  PHP.  Tambien  sera  necesario  asignar  al 
fichero  permisos  de  ejecucion.  De  esta  manera,  es  tratado  de  la  misma  manera  que  cualquier  otro  CGI 
script  escrito  en  Perl  o  sh  o  otro  lenguaje  utilizado  para  scripts  y  que  utilicen  el  mecanismo  #  !  para 
ejecutarse. 

Para  conseguir  que  PHP  maneje  correctamente  con  esta  configuracion,  la  informacion  de  PATH_INFO  y 
PATH_TRANSLATED,  el  analizador  PHP  deberia  ser  compilado  con  la  opcion  de  configuracion 
—enable -discard-path 
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Modulo  Apache 

Cuando  PHP  es  usado  como  modulo  Apache,  hereda  los  permisos  de  usuario  de  Apache  (normalmente 
"nobody”) 


38 


Parte  II.  Referenda  del  Lenguaje 


Capitulo  5.  Sintaxis  basica 


39 


Saliendo  de  HTML 


Capitulo  5.  Sintaxis  basica 


Hay  cuatro  formas  de  salir  de  HTML  y  entrar  en  el  "modo  de  codigo  PHP": 

Ejemplo  5-1.  Formas  de  salir  de  HTML 

1.  <?  echo  ("esta  es  la  mas  simple,  una  instruccion  de  procesado  SGML\n");  ?> 

2.  <?php  echo  ("si  quiere  servir  documentos  XML,  haga  esto\n") ;  ?> 

3.  <script  language="php"> 

echo  ("a  algunos  editores  (como  Frontpage)  no  les 
gustan  las  intrucciones  de  procesado"); 

</script> 

4.  <%  echo  ("Puedes  tambien  usar  etiquetas  tipo  ASP");  %> 

<%=  $variable;  #  Esto  es  una  forma  abreviada  de  "<%echo  . . "  %> 


La  primera  forma  solo  esta  disponible  si  se  han  habilitado  las  etiquetas  cortas.  Esto  se  puede  hacer  a 
traves  de  la  funcion  short_tags(),  habilitando  la  opcion  de  configuracion  short_open_tag  en  el  archivo  de 
configuration  de  PHP,  o  compilando  PHP  con  la  opcion  —enable-short-tags  en  configure. 

La  cuarta  manera  esta  disponible  solo  si  se  han  habilitado  las  etiquetas  tipo  ASP  usando  la  opcion  de 
configuracion  asp_tags 

Nota:  El  soporte  para  las  etiquetas  tipo  ASP  se  anadio  en  3.0.4. 


La  etiqueta  de  cierre  de  un  bloque  incluira  el  caracter  de  nueva  lrnea  final  si  hay  uno  presente. 


Separacion  de  instrucciones 

Las  instrucciones  se  separan  igual  que  en  C  o  perl  -  terminando  cada  sentencia  con  un  punto  y  coma. 
La  etiqueta  de  cierre  (?>)  tambien  implica  el  fin  de  la  sentencia,  asf  lo  siguiente  es  equivalente: 

<?php 

echo  "Esto  es  una  prueba"; 

?> 

<?php  echo  "Esto  es  una  prueba"  ?> 
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PHP  soporta  comentarios  tipo  ’C\  ’C++’  y  shell  de  Unix.  Por  ejemplo: 


<?php 

echo  "Esto  es  una  prueba";  //  Esto  es  un  comentario  tipo  C++  para  una  linea 
/*  Esto  es  un  comentario  multilinea 
otra  linea  mas  de  comentario*/ 
echo  "Esto  es  aun  otra  prueba"; 

echo  "Una  Prueba  Final";  #  Este  es  un  comentario  tipo  shell 


El  tipo  de  comentario  de  "una  linea"  solo  comenta,  en  realidad,  hasta  el  fin  de  la  linea  o  el  bloque  actual 
de  codigo  PHP,  lo  que  venga  primero. 

<hl>Esto  es  un  <?#  echo  "simple"; ?>  ejemplo . </hl> 

<p>La  cabecera  de  arriba  dira  'Esto  es  un  ejemplo' . 

Se  deberia  tener  cuidado  para  no  anidar  comentarios  de  tipo  ’C\  lo  cual  puede  ocurrir  cuando  se 
comentan  grandes  bloques. 

<?php 

/* 

echo  "Esto  es  una  prueba";  /*  Este  comentario  causara  un  problema  */ 

*/ 

?> 
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PHP  soporta  los  siguientes  tipos: 

•  array 

•  numeros  en  punto  flotante 

•  entero 


•  objeto 

•  cadena 


El  tipo  de  una  variable  normalmente  no  lo  indica  el  programador;  en  su  lugar,  lo  decide  PHP  en  tiempo 
de  ejecucion  dependiendo  del  contexto  en  el  que  se  utilice  esa  variable. 

Si  se  quisiese  obligar  a  que  una  variable  se  convierta  a  un  tipo  concreto,  se  podrfa  forzar  la  variable  o 
usar  la  funcion  settype')  para  ello. 

Notese  que  una  variable  se  puede  comportar  de  formas  diferentes  en  ciertas  situaciones,  dependiendo  de 
que  tipo  sea  en  ese  momento.  Para  mas  information,  vea  la  section  Conversion  de  Tipos 


Enteros 


Los  enteros  se  puede  especificar  usando  una  de  las  siguientes  sintaxis: 


$a  =  1234; 
$a  =  -123; 
$a  =  0123; 
$a  =  0x12; 


#  numero  decimal 

#  un  numero  negativo 

#  numero  octal  (equivalente  al  83  decimal) 

#  numero  hexadecimal  (equivalente  al  18  decimal) 


Numeros  en  punto  flotante 

Los  numeros  en  punto  flotante  ("double")  se  pueden  especificar  utilizando  cualquiera  de  las  siguientes 
sintaxis: 

$a  =  1.234;  $a  =  1.2e3; 


Cadenas 


Las  cadenas  de  caracteres  se  pueden  especificar  usando  uno  de  dos  tipos  de  delimitadores. 
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Si  la  cadena  esta  encerrada  entre  dobles  comillas  ("),  las  variables  que  esten  dentro  de  la  cadena  seran 
expandidas  (sujetas  a  ciertas  limitaciones  de  interpretation).  Como  en  C  y  en  Perl,  el  caracter  de  barra 
invertida  ("\")  se  puede  usar  para  especificar  caracteres  especiales: 


Tabla  6-1.  Caracteres  protegidos 


secuencia 

significado 

\n 

Nueva  lrnea 

\r 

Retorno  de  carro 

\t 

Tabulation  horizontal 

w 

Barra  invertida 

\$ 

Signo  del  dolar 

\" 

Comillas  dobles 

\  [0-7] {1,3} 

la  secuencia  de  caracteres  que  coincida  con  la 
expresion  regular  es  un  caracter  en  notacion  octal 

\x [0-9A-Fa-f] {1,2} 

la  secuencia  de  caracteres  que  coincida  con  la 
expresion  regular  es  un  caracter  en  notacion 
hexadecimal 

Se  puede  proteger  cualquier  otro  caracter,  pero  se  producira  una  advertencia  en  el  nivel  de  depuration 
mas  alto. 

La  segunda  forma  de  delimitar  una  cadena  de  caracteres  usa  el  caracter  de  comilla  simple  Cuando 
una  cadena  va  encerrada  entre  comillas  simples,  los  unicos  caracteres  de  escape  que  seran  comprendidos 
son  "\\"  y  "V".  Esto  es  por  convenio,  as!  que  se  pueden  tener  comillas  simples  y  barras  invertidas  en  una 
cadena  entre  comillas  simples.  Las  variables  no  se  expandiran  dentro  de  una  cadena  entre  comillas 
simples. 

Otra  forma  de  delimitar  cadenas  es  usando  la  sintaxis  de  documento  incrustado  ("»>").  Se  debe 
proporcionar  un  identificador  despues  de  >>>,  despues  la  cadena,  y  despues  el  mismo  identificador  para 
cerrar  el  entrecomillado. 

Ejemplo  6-1.  He  aquf  un  ejemplo  de  entrecomillado  de  cadenas  con  sintaxis  de  documento 
incrustado 

$str  =  »>EOD 

Ejemplo  de  cadena 

Expandiendo  multiples  lineas 

usando  sintaxis  de  documento  incrustado. 

EOD ; 


Nota:  La  sintaxis  de  documento  incristado  fue  anadida  en  PHP  4. 
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Las  cadenas  se  pueden  concatenar  usando  el  operador  (punto).  Notese  que  el  operador  ’+’  (suma)  no 
sirve  para  esto.  Por  favor  mire  Operadores  de  cadena  para  mas  information. 

Se  puede  acceder  a  los  caracteres  dentro  de  una  cadena  tratandola  como  un  array  de  caracteres  indexado 
numericamente,  usando  una  sintaxis  similar  a  la  de  C.  Vea  un  ejemplo  mas  abajo. 


Ejemplo  6-2.  Algumos  ejemplos  de  cadenas 

<?php 

/*  Asignando  una  cadena.  */ 

$str  =  "Esto  es  una  cadena"; 

/*  Anadiendo  a  la  cadena.  */ 

$str  =  $str  .  "  con  algo  mas  de  texto"; 

/*  Otra  forma  de  anadir,  incluye  un  caracter  de  nueva  linea  protegido.  */ 
$str  .=  "  Y  un  caracter  de  nueva  linea  al  final. \n"; 

/*  Esta  cadena  terminara  siendo  ' <p>Nuraero:  9</p>'  */ 

$num  =  9; 

$str  =  "<p>Numero:  $num</p>"; 

/*  Esta  sera  '<p>Numero:  $num</p>'  */ 

$num  =  9; 

$str  =  '<p>Numero:  $num</p>' ; 

/*  Obtener  el  primer  caracter  de  una  cadena  */ 

$str  =  'Esto  es  una  prueba.'; 

$f irst  =  $str [ 0 ] ; 

/*  Obtener  el  ultimo  caracter  de  una  cadena.  */ 

$str  =  'Esto  es  aun  una  prueba.'; 

$last  =  $str [strlen  ($str ) -1 ] ; 

?> 


Conversion  de  cadenas 

Cuando  una  cadena  se  evalua  como  un  valor  numerico,  el  valor  resultante  y  el  tipo  se  determinan  como 
sigue. 

La  cadena  se  evaluara  como  un  doble  si  contiene  cualquiera  de  los  caracteres  ’e’,  o  ’E’.  En  caso 
contrario,  se  evaluara  como  un  entero. 

El  valor  viene  dado  por  la  porcion  inicial  de  la  cadena.  Si  la  cadena  comienza  con  datos  de  valor 
numerico,  este  sera  el  valor  usado.  En  caso  contrario,  el  valor  sera  0  (cero).  Los  datos  numericos  validos 
son  un  signo  opcional,  seguido  por  uno  o  mas  digitos  (que  opcionalmente  contengan  un  punto  decimal), 
seguidos  por  un  exponente  opcional.  El  exponente  es  una  ’e’  o  una  ’E’  seguidos  por  uno  o  mas  digitos. 

Cuando  la  primera  expresion  es  una  cadena,  el  tipo  de  la  variable  dependera  de  la  segunda  expresion. 
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$  f oo  =  1  +  "10.5"; 

$ f oo  =  1  +  "-1 . 3e3" ; 

$  f oo  =  1  +  "bob-1. 3e3"; 

$  f oo  =  1  +  "bob3 " ; 

$foo  =  1  +  "10  Cerditos"; 
$foo  =  1  +  "10  Cerditos";  // 
$foo  =  "10.0  cerdos  "  +  1; 
$foo  =  "10.0  cerdos  "  +  1.0; 


//  $foo  es  entero  (11) 
$foo  es  entero  (11) 


//  $foo  es  doble  (11.5) 
//  $foo  es  doble  (-1299) 
//  $foo  es  entero  (1) 

//  $foo  es  entero  (1) 


//  $foo  es  entero  (11) 
//  $foo  es  double  (11) 


Para  mas  information  sobre  esta  conversion,  mire  en  la  pagina  del  manual  de  Unix  strtod(3). 

Si  quisiera  probar  cualquiera  de  los  ejemplos  de  esta  section,  puede  cortar  y  pegar  los  ejemplos  e  insertar 
la  siguiente  lrnea  para  ver  por  si  mismo  lo  que  va  ocurriendo: 

echo  " \$foo==$foo;  el  tipo  es  "  .  gettype  (  $foo  )  .  "<br>\n"; 


Arrays 


Los  arrays  actualmente  actuan  tanto  como  tablas  hash  (arrays  asociativos)  como  arrays  indexados 
(vectores). 


Arrays  unidimensionales 


PHP  soporta  tanto  arrays  escalares  como  asociativos.  De  hecho,  no  hay  diferencias  entre  los  dos.  Se 
puede  crear  una  array  usando  las  funciones  list')  o  array '),  o  se  puede  asignar  el  valor  de  cada  elemento 
del  array  de  manera  explicita. 

$  a [ 0 ]  =  "abc" ; 

$a [ 1 ]  =  "def"; 

$b [ "foo" ]  =  13; 


Tambien  se  puede  crear  un  array  simplemente  anadiendo  valores  al  array.  Cuando  se  asigna  un  valor  a 
una  variable  array  usando  corchetes  vacfos,  el  valor  se  anadira  al  final  del  array. 

$  a [ ]  =  "hola" ;  //  $a[2]  ==  "hola" 

$  a [ ]  =  "mundo";  //  $  a [ 3 ]  ==  "mundo" 


Los  arrays  se  pueden  ordenar  usando  las  funciones  asort  '),  arsort  '),  ksort'),  rsort  '),  sort  ),  uasort'), 
usort'),  y  uksort')  dependiendo  del  tipo  de  ordenacion  que  se  desee. 
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Se  puede  contar  el  numero  de  elementos  de  un  array  usando  la  funcion  count '). 

Se  puede  recorrer  un  array  usando  las  funciones  next  ')  y  prev)).  Otra  forma  habitual  de  recorrer  un  array 
es  usando  la  funcion  each)). 


Arrays  Multidimensionales 

Los  arrays  multidimensionales  son  bastante  simples  actualmente.  Para  cada  dimension  del  array,  se 
puede  anadir  otro  valor  [clave]  al  final: 


dimension 


$a[l]  =  $f ;  # 

$a [ " foo" ]  =  $f ; 

$a [1] [0]  =  $f ;  # 

$a [ " foo" ] [2]  =  $f ;  # 

$  a [ 3 ]  ["bar"]  =  $f;  # 

$a["foo"] [4] ["bar"] [0]  =  $f; 


ejemplos  de  una  sola 

bi dimensional 
(se  pueden  mezclar  indices 
(se  pueden  mezclar  indices 

#  tetradimensional ! 


numericos  y  asociativos) 
numericos  y  asociativos) 


En  PHP3  no  es  posible  referirse  a  arrays  multidimensionales  directamente  dentro  de  cadenas.  Por 
ejemplo,  lo  siguiente  no  tendra  el  resultado  deseado: 

$a [3] ['bar' ]  =  'Bob' ; 

echo  "Esto  no  va  a  funcionar:  $a[3] [bar]"; 

En  PHP3,  lo  anterior  tendra  la  salida  Esto  no  va  a  funcionar:  Array  [bar] .  De  todas  formas,  el 
operador  de  concatenation  de  cadenas  se  puede  usar  para  solucionar  esto: 

$a [3] ['bar' ]  =  'Bob' ; 

echo  "Esto  no  va  a  funcionar:  "  .  $a[3] [bar]; 


En  PHP4,  sin  embargo,  todo  el  problema  se  puede  circunvenir  encerrando  la  referencia  al  array  (dentro 
de  la  cadena)  entre  Haves: 

$a [3] ['bar' ]  =  'Bob' ; 

echo  "Esto  va  a  funcionar:  { $  a [ 3 ]  [bar]}"; 


Se  pueden  "rellenar"  arrays  multidimensionales  de  muchas  formas,  pero  la  mas  diffcil  de  comprender  es 
como  usar  el  comando  array))  para  arrays  asociativos.  Estos  dos  trozos  de  codigo  rellenaran  el  array 
unidimensional  de  la  misma  manera: 
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#  E jemplo  1 : 

$a["color"]  =  "rojo"; 
$a["sabor"]  =  "dulce"; 


$a 

[ " forma" ] 

_  ?! 

redondeada"  ; 

$a 

[ "nombre" ] 

= 

"manzana" ; 

$a 

[3]  =  4; 

#  Example  2 : 

$a 

=  array  ( 

"color" 

=  > 

"ro jo" , 

"sabor" 

=  > 

" dulce" , 

" forma" 

=  > 

"redondeada 

"nombre 

II 

=>  "manzana" 

3 

=  > 

4 

)  ; 


La  funcion  array ')  se  puede  anidar  para  arrays  multidimensionales: 

<? 

$a  =  array ( 


"manzana"  => 

array ( 

"color" 

=>  "rojo", 

"sabor" 

=>  "dulce", 

"forma" 

\ 

=>  "redondeada" 

l  r 

"naranja"  => 

array ( 

"color" 

=>  "naranja", 

"sabor" 

=>  "acido". 

"forma" 

=>  "redondeada" 

)  r 

"platano"  => 

array ( 

"color" 

=>  "amarillo", 

"sabor" 

=>  "paste-y", 

"forma" 

=>  "aplatanada" 

) 

)  ; 

echo  $a [ "manzana" ] ["sabor"] ;  #  devolvera  "dulce" 

?> 
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Inicializacion  de  Objetos 

Para  inicializar  un  objeto,  se  usa  la  sentencia  new  para  instanciar  el  objeto  a  una  variable. 

class  foo  { 

function  do_foo  ()  { 

echo  "Doing  foo."; 

} 

} 

$bar  =  new  foo; 

$bar->do_f oo ( ) ; 


Type  juggling 

PHP  no  requiere  (o  soporta)  la  declaration  explfcita  del  tipo  en  la  declaration  de  variables;  el  tipo  de  una 
variable  se  determina  por  el  contexto  en  el  que  se  usa  esa  variable.  Esto  quiere  decir  que  si  se  asigna  un 
valor  de  cadena  a  la  variable  var,  var  se  convierte  en  una  cadena.  Si  despues  se  asigna  un  valor  entero 
a  la  variable  var,  se  convierte  en  una  variable  entera. 

Un  ejemplo  de  conversion  de  tipo  automatica  en  PHP3  es  el  operador  suma  ’+’.  Si  cualquiera  de  los 
operandos  es  un  doble,  entonces  todos  los  operandos  se  evaluan  como  dobles,  y  el  resultado  sera  un 
doble.  En  caso  contrario,  los  operandos  se  interpretaran  como  enteros,  y  el  resultado  sera  tambien  un 
entero.  Notese  que  esto  NO  cambia  los  tipos  de  los  operandos  propiamente  dichos;  el  unico  cambio  esta 
en  como  se  evaluan  los  operandos. 

$foo  =  "0";  //  $foo  es  una  cadena  (ASCII  48) 

$foo++;  //  $foo  es  la  cadena  "1"  (ASCII  49) 

$foo  +=  1;  //  $foo  ahora  es  un  entero  (2) 

$foo  =  $foo  +  1.3;  //  $foo  ahora  es  un  doble  (3.3) 

$foo  =  5  +  "10  Cerditos  Pequenitos";  //  $foo  es  entero  (15) 

$foo  =  5  +  "10  Cerditos";  //  $foo  es  entero  (15) 


Si  los  ultimos  dos  ejemplos  anteriores  parecen  confusos,  vea  Conversion  de  cadenas 

Si  se  desea  obligar  a  que  una  variable  sea  evaluada  con  un  tipo  concreto,  mire  la  seccion  Forzado  de 
tipos  Si  se  desea  cambiar  el  tipo  de  una  variable,  vea  la  funcion  settype '). 

Si  quisiese  probar  cualquiera  de  los  ejemplos  de  esta  seccion,  puede  cortar  y  pegar  los  ejemplos  e 
insertar  la  siguiente  linea  para  ver  por  sf  mismo  lo  que  va  ocurriendo: 
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echo  " \$foo==$f oo;  el  tipo  es  "  .  gettype  (  $foo  )  .  "<br>\n"; 


Nota:  La  posibilidad  de  una  conversion  automatica  a  array  no  esta  definida  actualmente. 

$a  =  1;  //  $a  es  un  entero 

$a[0]  =  "f";  //  $a  se  convierte  en  un  array,  en  el  que  $a[0]  vale  "f" 


Aunque  el  ejemplo  anterior  puede  parecer  que  claramente  deberia  resultar  en  que  $a  se  convierta 
en  un  array,  el  primer  elemento  del  cual  es  T,  consideremos  esto: 


$a  =  "1";  //  $a  es  una  cadena 

$a[0]  =  "f";  //  iQue  pasa  con  los  indices  de  las  cadenas?  iQue  ocurre? 


Dado  que  PHP  soporta  indexacion  en  las  cadenas  via  offsets  usando  la  misma  sintaxis  que  la 
indexacion  de  arrays,  el  ejemplo  anterior  nos  conduce  a  un  problema:  ideberfa  convertirse  $a  en  un 
array  cuyo  primer  elemento  sea  "f",  o  deberia  convertirse  "f"  en  el  primer  caracter  de  la  cadena  $a? 

Por  esta  razon,  tanto  en  PHP  3.0.12  como  en  PHP  4.0b3-RC4,  el  resultado  de  esta  conversion 
automatica  se  considera  que  no  esta  definido.  Los  parches  se  estan  discutiendo,  de  todas  formas. 


Forzado  de  tipos 

El  forzado  de  tipos  en  PHP  funciona  como  en  C:  el  nombre  del  tipo  deseado  se  escribe  entre  parentesis 
antes  de  la  variable  a  la  que  se  pretende  forzar. 

$foo  =  10;  //  $foo  es  un  entero 

$bar  =  (double)  $foo;  //  $bar  es  un  doble 


Los  forzados  de  tipo  permitidos  son: 

•  (int),  (integer)  -  fuerza  a  entero  (integer) 

•  (real),  (double),  (float)  -  fuerza  a  doble  (double) 

•  (string)  -  fuerza  a  cadena  (string) 

•  (array)  -  fuerza  a  array  (array) 

•  (object)  -  fuerza  a  objeto  (object) 
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Notese  que  las  tabulaciones  y  espacios  se  permiten  dentro  de  los  parentesis,  asf  que  los  siguientes 
ejemplos  son  funcionalmente  equivalentes: 

$foo  =  (int)  $bar; 

$foo  =  (  int  )  $bar; 


Puede  no  ser  obvio  que  ocurrira  cuando  se  fuerce  entre  ciertos  tipos.  Por  ejemplo,  lo  siguiente  deberfa  ser 
tenido  en  cuenta. 

Cuando  se  fuerza  el  cambio  de  un  escalar  o  una  variable  de  cadena  a  un  array,  la  variable  se  convertira  en 
el  primer  elemento  del  array: 

$var  =  ' ciao' ; 

$arr  =  (array)  $var; 

echo  $arr[0];  //  produce  la  salida  'ciao' 


Cuando  se  fuerza  el  tipo  de  una  variable  escalar  o  de  una  cadena  a  un  objeto,  la  variable  se  convertira  en 
un  atributo  del  objeto;  el  nombre  del  atributo  sera  ’scalar’: 

$var  =  ' ciao' ; 

$obj  =  (object)  $var; 

echo  $ob j->scalar;  //  produce  la  salida  'ciao' 
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Conceptos  Basicos 

En  PHP  las  variables  se  representan  como  un  signo  de  dolar  seguido  por  el  nombre  de  la  variable.  El 
nombre  de  la  variable  es  sensible  a  minusculas  y  mayusculas. 

$var  =  "Bob"; 

$Var  =  "Joe"; 

echo  "$var,  $Var";  //  produce  la  salida  "Bob,  Joe" 


En  PHP3,  las  variables  siempre  se  asignan  por  valor.  Esto  significa  que  cuando  se  asigna  una  expresion  a 
una  variable,  el  valor  Integra  de  la  expresion  original  se  copia  en  la  variable  de  destino.  Esto  quiere  decir 
que,  por  ejemplo,  despues  e  asignar  el  valor  de  una  variable  a  otra,  los  cambios  que  se  efectuen  a  una  de 
esas  variables  no  afectara  a  la  otra.  Para  mas  information  sobre  este  tipo  de  asignacion,  vea  Expresiones 

PHP4  ofrece  otra  forma  de  asignar  valores  a  las  variables:  asignar  por  referenda.  Esto  significa  que  la 
nueva  variable  simplemente  referencia  (en  otras  palabras,  "se  convierte  en  un  alias  de"  o  "apunta  a")  la 
variable  original.  Los  cambios  a  la  nueva  variable  afectan  a  la  original,  y  viceversa.  Esto  tambien 
significa  que  no  se  produce  una  copia  de  valores;  por  tanto,  la  asignacion  ocurre  mas  rapidamente.  De 
cualquier  forma,  cualquier  incremento  de  velocidad  se  notara  solo  en  los  bucles  crfticos  cuando  se 
asignen  grandes  arrays  u  objetos. 

Para  asignar  por  referencia,  simplemente  se  antepone  un  ampersand  (&)  al  comienzo  de  la  variable  cuyo 
valor  se  esta  asignando  (la  variable  fuente).  Por  ejemplo,  el  siguiente  trozo  de  codigo  produce  la  salida 
’Mi  nombre  es  Bob’  dos  veces: 

<?php 

$foo  =  'Bob';  //  Asigna  el  valor  'Bob'  a  $foo 

$bar  =  &$foo;  //  Referencia  $foo  via  $bar. 

$bar  =  "Mi  nombre  es  $bar";  //  Modifica  $bar . . . 

echo  $foo;  //  $foo  tambien  se  modifica. 

echo  $bar; 

?> 


Algo  importante  a  tener  en  cuenta  es  que  solo  las  variables  con  nombre  pueden  ser  asignadas  por 
referencia. 


<?php 

$foo  =  25; 

$bar  =  &$foo;  //  Esta  es  una  asignacion  valida. 

$bar  =  &(24  *  7);  //  Invalida;  referencia  una  expresion  sin  nombre. 

function  test()  { 
return  25; 

} 


$bar  =  Stest  ( ) ; 


//  Invalida. 
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?> 


Variables  predefinidas 

PHP  proporciona  una  gran  cantidad  de  variables  predefinidas  a  cualquier  script  que  se  ejecute.  De  todas 
formas,  muchas  de  esas  variables  no  pueden  estar  completamente  documentadas  ya  que  dependen  de 
sobre  que  servidor  se  este  ejecutando,  la  version  y  configuracion  de  dicho  servidor,  y  otros  factores. 
Algunas  de  estas  variables  no  estaran  disponibles  cuando  se  ejecute  PHP  desde  la  lfnea  de  comandos. 

A  pesar  de  estos  factores,  aquf  tenemos  una  lista  de  variables  predefinidas  disponibles  en  una  instalacion 
por  defecto  de  PHP  3  corriendo  como  modulo  de  un  Apache  (http://www.apache.org/)  1.3.6  con  su 
configuracion  tambien  por  defecto. 

Para  una  lista  de  variables  predefinidas  (y  muchas  mas  informacion  util),  por  favor,  vea  (y  use)  phpinfo  ). 

Nota:  Esta  lista  no  es  exhaustiva  ni  pretende  serlo.  Simplemente  es  una  gufa  de  que  tipo  de 
variables  predefinidas  se  puede  esperar  tener  disponibles  en  un  script. 


Variables  de  Apache 

Estas  variables  son  creadas  por  el  servidor  web  Apache  (http://www.apache.org/).  Si  se  esta  utilizando 
otro  servidor  web,  no  hay  garantfa  de  que  proporcione  las  mismas  variables;  pueden  faltar  algunas,  o 
proporcionar  otras  no  listadas  aquf.  Dicho  esto,  tambien  estan  presentes  las  variables  de  la  especificacion 
CGI  1.1  (http://hoohoo.ncsa.uiuc.edu/cgi/env.html),  por  lo  que  tambien  se  deben  tener  en  cuenta. 

Tenga  en  cuenta  que  unas  pocas,  como  mucho,  de  estas  variables  van  a  estar  disponibles  (o  simplemente 
tener  sentido)  si  se  ejecuta  PHP  desde  la  lfnea  de  comandos. 


GATEWAYJNTERFACE 

Que  revision  de  la  especificacion  CGI  esta  usando  el  servidor;  por  ejemplo  ’CGI/1.1’. 
SERVER_NAME 

El  nombre  del  equipo  servidor  en  el  que  se  esta  ejecutando  el  script.  Si  el  script  se  esta  ejecutando 
en  un  servidor  virtual,  este  sera  el  valor  definido  para  dicho  servidor  virtual. 

SERVER_SOFTWARE 

Una  cadena  de  identificacion  del  servidor,  que  aparece  en  las  cabeceras  al  responderse  a  las 
peticiones. 

SERVER_PROTOCOL 

Nombre  y  revision  del  protocolo  a  traves  del  que  se  solicito  la  pagina;  p.ej.  ’HTTP/1. O’; 
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REQUEST_METHOD 

Que  metodo  de  peticion  se  uso  para  acceder  a  la  pagina;  p.ej.  ’GET’,  ’HEAD’,  ’POST’,  ’PUT’. 
QUERY_STRING 

La  cadena  de  la  peticion,  si  la  hubo,  mediante  la  que  se  accedio  a  la  pagina. 
DOCUMENT_ROOT 

El  directorio  rafz  del  documento  bajo  el  que  se  ejecuta  el  script,  tal  y  como  esta  definido  en  el 
fichero  de  configuration  del  servidor. 


HTTP_ACCEPT 

Los  contenidos  de  la  cabecera  Accept :  de  la  peticion  actual,  si  hay  alguna. 
HTTP_ACCEPT_CHARSET 

Los  contenidos  de  la  cabecera  Accept-Charset :  de  la  peticion  actual,  si  hay  alguna.  Por 
ejemplo:  ’iso-8859-1, *,utf-8’. 

http_encoding 

Los  contenidos  de  la  cabecera  Accept -Encoding :  de  la  peticion  actual,  si  la  hay.  Por  ejemplo: 
’gzip’. 

HTTP_ACCEPT_LANGUAGE 

Los  contenidos  de  la  cabecera  Accept -Language :  de  la  peticion  actual,  si  hay  alguna.  Por 
ejemplo:  ’en’. 

HTTP_CONNECTION 

Los  contenidos  de  la  cabecera  Connection :  de  la  peticion  actual,  si  hay  alguna.  Por  ejemplo: 
’Keep-Alive’. 


HTTP_HOST 

Los  contenidos  de  la  cabecera  Host :  de  la  peticion  actual,  si  hay  alguna. 

HTTP_RELERER 

La  direccion  de  la  pagina  (si  la  hay)  desde  la  que  el  navegador  salto  a  la  pagina  actual.  Esto  lo 
establece  el  navegador  del  usuario;  no  todos  los  navegadores  lo  hacen. 

HTTP_USER_AGENT 

Los  contenidos  de  la  cabecera  User_Agent :  de  la  peticion  actual,  si  hay  alguna.  Indica  el 
navegador  que  se  esta  utilizando  para  ver  la  pagina  actual;  p.ej.  Mozilla/4 . 5  [en]  (xil;  U; 
Linux  2.2.9  1586) .  Entre  otras  cosas,  se  puede  usar  este  valor  con  get_browser')  para  adaptar  la 
funcionalidad  de  la  pagina  a  las  posibilidades  del  navegador  del  usuario. 

REMOTE_ADDR 

La  direccion  IP  desde  la  que  el  usuario  esta  viendo  la  pagina  actual. 
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REMOTE_PORT 

El  puerto  que  se  esta  utilizando  en  la  maquina  del  usuario  para  comunicarse  con  el  servidor  web. 
SCRIPT_FILENAME 

La  via  de  acceso  absoluta  del  script  que  se  esta  ejecutando. 

SERVER_ADMIN 

El  valor  que  se  haya  dado  a  la  directiva  SERVER_ADMIN  (en  Apache)  en  el  fichero  de 
configuracion  del  servidor  web.  Si  el  script  se  esta  ejecutando  en  un  servidor  virtual,  sera  el  valor 
definido  para  dicho  servidor  virtual. 


SERVER_PORT 

El  puerto  del  equipo  servidor  que  esta  usando  el  servidor  web  para  la  comunicacion.  Para 
configuraciones  por  defecto,  sera  ’80’;  al  usar  SSL,  por  ejemplo,  cambiara  al  puerto  que  se  haya 
definido  como  seguro  para  HTTP. 

SERVER_SIGNATURE 

Una  cadena  que  contiene  la  version  del  servidor  y  el  nombre  del  servidor  virtual  que  es  anadida  a 
las  paginas  generadas  por  el  servidor,  si  esta  caracterfstica  esta  activa. 

PATH_TRANSLATED 

Via  de  acceso  basada  en  el  sistema  de  ficheros-  (no  el  directorio  rafz  del  documento-)  del  script  en 
cuestion,  despues  de  que  el  servidor  haya  hecho  la  conversion  virtual- a-real. 


SCRIPT_NAME 

Contiene  la  via  de  acceso  del  script  actual.  Es  util  para  paginas  que  necesitan  apuntar  a  si  mismas. 

REQUEST_URI 

La  URI  que  se  dio  para  acceder  a  esta  pagina;  por  ejemplo,  7index.html’. 


Variables  de  entorno 

Estas  variables  se  importan  en  el  espacio  de  nombres  global  de  PHP  desde  el  entorno  en  el  que  se  este 
ejecutando  el  interprete  PHP.  Muchas  son  proporcionadas  por  el  interprete  de  comandos  en  el  que  se  esta 
ejecutando  PHP,  y  dado  que  a  sistemas  diferentes  les  gusta  ejecutar  diferentes  tipos  de  interpretes  de 
comandos,  es  imposible  hacer  una  lista  definitiva.  Por  favor,  mire  la  documentacion  de  su  interprete  de 
comandos  para  ver  una  lista  de  las  variables  de  entorno  definidas. 

Otras  variables  de  entorno  son  las  de  CGI,  que  estan  ahf  sin  importar  si  PHP  se  esta  ejecutando  como  un 
modulo  del  servidor  o  como  un  interprete  CGI. 


Variables  de  PHP 


Estas  variables  son  creadas  por  el  propio  PHP. 
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argv 

Array  de  argumentos  pasados  al  script.  Cuando  el  script  se  ejecuta  desde  la  lmea  de  comandos,  esto 
da  un  acceso,  al  estilo  de  C,  a  los  parametros  pasados  en  lmea  de  comandos.  Cuando  se  le  llama 
mediante  el  metodo  GET,  contendra  la  cadena  de  la  peticion. 

argc 

Contiene  el  numero  de  parametros  de  la  lmea  de  comandos  pasados  al  script  (si  se  ejecuta  desde  la 
Hnea  de  comandos). 


PHP_SELF 

El  nombre  del  fichero  que  contiene  el  script  que  se  esta  ejecutando,  relativo  al  directorio  rafz  de  los 
documentos.  Si  PHP  se  esta  ejecutando  como  interprete  de  lmea  de  comandos,  esta  variable  no  esta 
disponible. 

HTTP_COOKIE_VARS 

Un  array  asociativo  de  variables  pasadas  al  script  actual  mediante  cookies  HTTP.  Solo  esta 
disponible  si  el  seguimiento  de  variables  ha  sido  activado  mediante  la  directiva  de  configuracion 
track_vars  o  la  directiva  <?php_track_vars?>. 

HTTP_GET_VARS 

Un  array  asociativo  de  variables  pasadas  al  script  actual  mediante  el  metodo  HTTP  GET.  Solo  esta 
disponible  si  —variable  tracking—  ha  sido  activado  mediante  la  directiva  de  configuracion  track_vars 
o  la  directiva  <?php_track_vars?>. 

HTTP_POST_VARS 

Un  array  asociativo  de  variables  pasadas  al  script  actual  mediante  el  metodo  HTTP  POST.  Solo  esta 
disponible  si  —variable  tracking—  ha  sido  activado  mediante  la  directiva  de  configuracion  track_vars 
o  la  directiva  <?php_track_vars?>. 


Ambito  de  las  variables 


El  ambito  de  una  variable  es  el  contexto  dentro  del  que  la  variable  esta  definida.  La  mayor  parte  de  las 
variables  PHP  solo  tienen  un  ambito  simple.  Este  ambito  simple  tambien  abarca  los  ficheros  incluidos  y 
los  requeridos.  Por  ejemplo: 

$a  =  1; 

include  "b.inc"; 


Aquf,  la  variable  $a  dentro  del  script  incluido  b.inc.  De  todas  formas,  dentro  de  las  funciones  definidas 
por  el  usuario  aparece  un  ambito  local  a  la  funcion.  Cualquier  variables  que  se  use  dentro  de  una  funcion 
esta,  por  defecto,  limitada  al  ambito  local  de  la  funcion.  Por  ejemplo: 
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$a  =  1;  /*  ambito  global  */ 

Function  Test  ()  { 

echo  $a;  /*  referenda  a  una  variable  de  ambito  local  */ 

} 

Test  ( ) ; 


Este  script  no  producira  salida,  ya  que  la  orden  echo  utiliza  una  version  local  de  la  variable  $a,  a  la  que 
no  se  ha  asignado  ningun  valor  en  su  ambito.  Puede  que  usted  note  que  hay  una  pequena  diferencia  con 
el  lenguaje  C,  en  el  que  las  variables  globales  estan  disponibles  automaticamente  dentro  de  la  funcion  a 
menos  que  sean  expresamente  sobreescritas  por  una  definicion  local.  Esto  puede  causar  algunos 
problemas,  ya  que  la  gente  puede  cambiar  variables  globales  inadvertidamente.  En  PHP,  las  variables 
globales  deben  ser  declaradas  globales  dentro  de  la  funcion  si  van  a  ser  utilizadas  dentro  de  dicha 
funcion.  Veamos  un  ejemplo: 

$a  =  1; 

$b  =  2; 

Function  Sum  ()  { 

global  $a,  $b; 

$b  =  $a  +  $b; 

} 

Sum  ( ) ; 
echo  $b; 


El  script  anterior  producira  la  salida  "3".  A1  declarar  $a  y  $b  globales  dentro  de  la  funcion,  todas  las 
referencias  a  tales  variables  se  referiran  a  la  version  global.  No  hay  limite  al  nurnero  de  variables 
globales  que  se  pueden  manipular  dentro  de  una  funcion. 

Un  segundo  metodo  para  acceder  a  las  variables  desde  un  ambito  global  es  usando  el  array  $GLOBALS 
propio  de  PHP3.  El  ejemplo  anterior  se  puede  reescribir  asf: 

$a  =  1; 

$b  =  2; 

Function  Sum  ()  { 

SGLOBALS [ "b" ]  =  $GLOBALS [ " a" ]  +  $ GLOBAL S [ "b" ]  ; 

} 

Sum  ( ) ; 
echo  $b; 


El  array  $GLOBALS  es  un  array  asociativo  con  el  nombre  de  la  variable  global  como  clave  y  los 
contenidos  de  dicha  variable  como  el  valor  del  elemento  del  array. 
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Otra  caracterfstica  importante  del  ambito  de  las  variables  es  la  variable  static.  Una  variable  estatica  existe 
solo  en  el  ambito  local  de  la  funcion,  pero  no  pierde  su  valor  cuando  la  ejecucion  del  programa  abandona 
este  ambito.  Consideremos  el  siguiente  ejemplo: 

Function  Test  ()  { 

$a  =  0; 
echo  $a; 

$a+  +  ; 

} 


valor  0  y  representa  un 
en  cuanto  la  funcion 
no  pierda  la  pista  del  valor 


Function  Test  ()  { 

static  $a  =  0; 
echo  $a; 

$a+  +  ; 

} 


Esta  funcion  tiene  poca  utilidad  ya  que  cada  vez  que  es  llamada  asigna  a  $a  el 
"0".  La  sentencia  $a++,  que  incrementa  la  variable,  no  sirve  para  nada,  ya  que 
termina  la  variable  $a  desaparece.  Para  hacer  una  funcion  util  para  contar,  que 
actual  del  conteo,  la  variable  $a  debe  declararse  como  estatica: 


Ahora,  cada  vez  que  se  llame  a  la  funcion  Test(),  se  representara  el  valor  de  $a  y  se  incrementara. 

Las  variables  estaticas  tambien  proporcionan  una  forma  de  manejar  funciones  recursivas.  Una  funcion 
recursiva  es  la  que  se  llama  a  si  misma.  Se  debe  tener  cuidado  al  escribir  una  funcion  recursiva,  ya  que 
puede  ocurrir  que  se  llame  a  sf  misma  indefinidamente.  Hay  que  asegurarse  de  implementar  una  forma 
adecuada  de  terminar  la  recursion.  La  siguiente  funcion  cuenta  recursivamente  hasta  10,  usando  la 
variable  estatica  $count  para  saber  cuando  parar: 

Function  Test  ()  { 

static  $count  =  0; 

$count++ ; 

echo  $count; 

if  ($count  <  10)  { 

Test  ( ) ; 

} 

$count — ; 

} 


Variables  variables 


A  veces  es  conveniente  tener  nombres  de  variables  variables.  Dicho  de  otro  modo,  son  nombres  de 
variables  que  se  pueden  establecer  y  usar  dinamicamente.  Una  variable  normal  se  establece  con  una 
sentencia  como: 
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$a  =  "hello"; 

Una  variable  variable  toma  el  valor  de  una  variable  y  lo  trata  como  el  nombre  de  una  variable.  En  el 
ejemplo  anterior,  hello ,  se  puede  usar  como  el  nombre  de  una  variable  utilizando  dos  signos  de  dolar. 
P-ej. 

$$a  =  "world"; 


En  este  momento  se  han  definido  y  almacenado  dos  variables  en  el  arbol  de  sfmbolos  de  PHP:  $a,  que 
contiene  "hello",  y  $hello,  que  contiene  "world".  Es  mas,  esta  sentencia: 

echo  " $a  $ { $a } " ; 


produce  el  mismo  resultado  que: 

echo  "$a  $hello"; 

p.ej.  ambas  producen  el  resultado:  hello  world. 

Para  usar  variables  variables  con  arrays,  hay  que  resolver  un  problema  de  ambigiiedad.  Si  se  escribe 
$$a[l]  el  interprete  necesita  saber  si  nos  referimos  a  utilizar  $a[l]  como  una  variable,  o  si  se  pretendfa 
utilizar  $$a  como  variable  y  el  fndice  [1]  como  indice  de  dicha  variable.  La  sintaxis  para  resolver  esta 
ambiguedad  es:  ${$a[l] }  para  el  primer  caso  y  ${$a}[l]  para  el  segundo. 


Variables  externas  a  PHP 

Formularios  HTML  (GET  y  POST) 

Cuando  se  envfa  un  formulario  a  un  script  PHP,  las  variables  de  dicho  formulario  pasan  a  estar 
automaticamente  disponibles  en  el  script  gracias  a  PHP.  Por  ejemplo,  consideremos  el  siguiente 
formulario: 


Ejemplo  7-1.  Variables  de  formulario  simples 

<form  action="foo .php3"  method="post " > 

Name:  <input  type="text"  name="name"xbr> 
<input  type=" submit " > 

</ f orm> 


Cuando  es  enviado,  PHP  creara  la  variable  $name,  que  contendra  lo  que  sea  que  se  introdujo  en  el  campo 
Name:  del  formulario. 
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PHP  tambien  maneja  arrays  en  el  contexto  de  variables  de  formularios,  pero  solo  en  una  dimension.  Se 
puede,  por  ejemplo,  agrupar  juntas  variables  relacionadas,  o  usar  esta  caracterfstica  para  recuperar 
valores  de  un  campo  select  input  multiple: 

Ejemplo  7-2.  Variables  de  formulario  mas  complejas 

<form  action="array . php"  method="post"> 

Name:  <input  type="text"  name="personal [name] "><br> 

Email:  <input  type="text"  name="personal [email] "><br> 

Beer:  <br> 

<select  multiple  name="beer [ ] "> 

<opt ion  value=" wart hog" >Warthog 
<option  value="guinness">Guinness 

<option  value="stuttgarter">Stuttgarter  Schwabenbrau 
</ select> 

<input  type=" submit " > 

</ f orm> 


Si  la  posibilidad  de  PHP  de  track_vars  esta  activada,  ya  sea  mediante  la  opcion  de  configuracion 
track_vars  o  mediante  la  directiva  <?php_track_vars?>,  las  variables  enviadas  con  los  metodos  POST 
o  GET  tambien  se  encontraran  en  los  arrays  asociativos  globales  $HTTP_POST_VARS  y 
$HTTP_GET_VARS . 

IMAGE  SUBMIT  variable  names 

Cuando  se  envfa  un  formulario,  es  posible  usar  una  imagen  en  vez  del  boton  submit  estandar  con  una 
etiqueta  como: 

<input  type=image  src="image . gif "  name="sub"> 


Cuando  el  usuario  hace  click  en  cualquier  parte  de  la  imagen,  el  formulario  que  la  acompana  se 
transmitira  al  servidor  con  dos  variables  adicionales,  sub_x  y  sub_y.  Estas  contienen  las  coordenadas  del 
click  del  usuario  dentro  de  la  imagen.  Los  mas  experimentados  puede  notar  que  los  nombres  de  variable 
enviados  por  el  navegador  contienen  un  guion  en  vez  de  un  subrayado  (guion  bajo),  pero  PHP  convierte 
el  guion  en  subrayado  automaticamente. 


Cookies  HTTP 

PHP  soporta  cookies  de  HTTP  de  forma  transparente  tal  y  como  estan  definidas  en  en  las  Netscape’s 
Spec  (http://www.netscape.com/newsref/std/cookie_spec.html).  Las  cookies  son  un  mecanismo  para 
almacenar  datos  en  el  navegador  y  asf  rastrear  o  identificar  a  usuarios  que  vuelven.  Se  pueden  crear 
cookies  usando  la  funcion  SetCookie().  Las  cookies  son  parte  de  la  cabecera  HTTP,  asf  que  se  debe 
llamar  a  la  funcion  SetCookie  antes  de  que  se  envfe  cualquier  salida  al  navegador.  Es  la  misma 
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restriccion  que  para  la  funcion  header^).  Cualquier  cookie  que  se  reciba  procedente  del  cliente  sera 
convertida  automaticamente  en  una  variable  de  PHP  como  con  los  datos  en  los  metodos  GET  y  POST. 

Si  se  quieren  asignar  multiples  valores  a  una  sola  cookie,  basta  con  anadir  [ /  al  nombre  de  la.  Por 
ejemplo: 

SetCookie  ( "MyCookie [ ] " ,  "Testing",  time () +3600)  ; 

Notese  que  una  cookie  reemplazara  a  una  cookie  anterior  que  tuviese  el  mismo  nombre  en  el  navegador  a 
menos  que  el  camino  (path)  o  el  dominio  fuesen  diferentes.  Asi,  para  una  aplicacion  de  carro  de  la 
compra  se  podrfa  querer  mantener  un  contador  e  ir  pasandolo.  P.ej. 

Ejemplo  7-3.  SetCookie  Example 

$Count++; 

SetCookie  ("Count",  $Count,  time () +3600) ; 

SetCookie  ( "Cart [ $Count ] " ,  $item,  time  0+3600); 


Variables  de  entorno 

PHP  hace  accesibles  las  variables  de  entorno  automaticamente  tratandolas  como  variables  normales. 

echo  $H0ME;  /*  Shows  the  HOME  environment  variable,  if  set.  */ 


Dado  que  la  information  que  llega  via  mecanismos  GET,  POST  y  Cookie  crean  automaticamente 
variables  de  PHP,  algunas  veces  es  mejor  leer  variables  del  entorno  explicitamente  para  asegurarse  de 
que  se  esta  trabajando  con  la  version  correcta.  La  funcion  getenv ')  se  puede  usar  para  ello.  Tambien  se 
puede  asignar  un  valor  a  una  variable  de  entorno  con  la  funcion  putenv  '). 


Puntos  en  los  nombres  de  variables  de  entrada 

Tipicamente,  PHP  no  altera  los  nombres  de  las  variables  cuando  se  pasan  a  un  script.  De  todas  formas, 
hay  que  notar  que  el  punto  no  es  un  caracter  valido  en  el  nombre  de  una  variable  PHP.  Por  esta  razon, 
mire  esto: 

$varname . ext ;  /*  nombre  de  variable  no  valido  */ 


Lo  que  el  interprete  ve  es  el  nombre  de  una  variable  Svamame,  seguido  por  el  operador  de  concatenation, 
y  seguido  por  la  prueba  (es  decir,  una  cadena  sin  entrecomillar  que  no  coincide  con  ninguna  palabra 
clave  o  reservada  conocida)  ’ext’.  Obviamente,  no  se  pretendfa  que  fuese  este  el  resultado. 

Por  esta  razon,  es  importante  hacer  notar  que  PHP  reemplazara  automaticamente  cualquier  punto  en  los 
nombres  de  variables  de  entrada  por  guiones  bajos  (subrayados). 
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Determinando  los  tipos  de  variables 

Dado  que  PHP  determina  los  tipos  de  las  variables  y  los  convierte  (generalmente)  segun  necesita,  no 
siempre  resulta  obvio  de  que  tipo  es  una  variable  dada  en  un  momento  concreto.  PHP  incluye  varias 
funciones  que  descubren  de  que  tipo  es  una  variable.  Son  gettype '),  is_long '),  is_double  Q,  is_string  '), 
is_array'),  y  is_object '). 
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PHP  define  varias  constantes  y  proporciona  un  mecanismo  para  definir  mas  en  tiempo  de  ejecucion.  Las 
constantes  son  como  las  variables,  salvo  por  las  dos  circunstancias  de  que  las  constantes  deben  ser 
definidas  usando  la  funcion  define '),  y  que  no  pueden  ser  redefinidas  mas  tarde  con  otro  valor. 

Las  constantes  predefinidas  (siempre  disponibles)  son: 


FILE _ 

El  nombre  del  archivo  de  comandos  que  esta  siendo  interpretado  actualmente.  Si  se  usa  dentro  de 
un  archivo  que  ha  sido  incluido  o  requerido,  entonces  se  da  el  nombre  del  archivo  incluido,  y  no  el 
nombre  del  archivo  padre. 

.LINE _ 

El  numero  de  lfnea  dentro  del  archivo  que  esta  siendo  interpretado  en  la  actualidad.  Si  se  usa  dentro 
de  un  archivo  incluido  o  requerido,  entonces  se  da  la  posicion  dentro  del  archivo  incluido. 


PHP_  V  ERS  ION 


PHP_OS 


TRUE 


FALSE 


La  cadena  que  representa  la  version  del  analizador  de  PHP  en  uso  en  la  actualidad;  e.g.  ’3.0.8-dev’. 


El  nombre  del  sistema  operativo  en  el  cual  se  ejecuta  el  analizador  PHP;  e.g.  ’Linux’. 


Valor  verdadero. 


Valor  falso. 

E_ERROR 

Denota  un  error  distinto  de  un  error  de  interpretacion  del  cual  no  es  posible  recuperarse. 

E_WARNING 

Denota  una  condicion  donde  PHP  reconoce  que  hay  algo  erroneo,  pero  continuara  de  todas  formas; 
pueden  ser  capturados  por  el  propio  archivo  de  comandos.  Un  ejemplo  serfa  una  invalida  regexp  en 
eregO. 


E_PARSE 

El  interprete  encontro  sintaxis  invalida  en  el  archivo  de  comandos.  La  recuperacion  no  es  posible. 

E_NOTICE 

Ocurrio  algo  que  pudo  ser  o  no  un  error.  La  ejecucion  continua.  Los  ejemplos  incluyen  usar  una 
cadena  sin  comillas  como  un  mdice  "hash",  o  acceder  a  una  variable  que  no  ha  sido  inicializada. 


Las  constantes  E_*  se  usan  tfpicamente  con  la  funcion  error_reporting')  para  configurar  el  nivel  de 
informes  de  error. 

Se  pueden  definir  constantes  adicionales  usando  la  funcion  define')- 
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Notese  que  son  constantes,  no  macros  tipo  C;  con  una  constante  solo  se  pueden  representar  datos 
escalares  validos. 

Ejemplo  8-1.  Definiendo  Constantes 


<?php 

define ( "CONSTANTE " ,  "Hola  raundo . " ) ; 
echo  CONSTANTE;  //  muestra  "Hola  raundo . " 
?> 


Ejemplo  8-2.  Usando _ FILE _ y _ LINE _ 

<?php 

function  report_error ($file,  $line,  $message)  { 

echo  "Un  error  occurrio  en  $file  en  la  linea  $line:  $message."; 

} 

report_error ( _ FILE _ , _ LINE _ ,  "Algo  fue  mail"); 

?> 
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Las  expresiones  son  la  piedra  angular  de  PHP.  En  PHP,  casi  cualquier  cosa  que  escribes  es  una  expresion. 
La  forma  mas  simple  y  ajustada  de  definir  una  expresion  es  "cualquier  cosa  que  tiene  un  valor". 

Las  formas  mas  basicas  de  expresiones  son  las  constantes  y  las  variables.  Cuando  escribes  "$a  =  5",  estas 
asignando  ’5’  a  $a.  ’5’,  obviamente,  tiene  el  valor  5  o,  en  otras  palabras  ’5’  es  una  expresion  con  el  valor 
5  (en  este  caso,  ’5’  es  una  constante  entera). 

Despues  de  esta  asignacion,  esperaras  que  el  valor  de  $a  sea  5  tambien,  de  manera  que  si  escribes  $b  = 
$a,  esperas  que  se  comporte  igual  que  si  escribieses  $b  =  5.  En  otras  palabras,  $a  es  una  expresion 
tambien  con  el  valor  5.  Si  todo  va  bien,  eso  es  exactamente  lo  que  pasara. 

Las  funciones  son  un  ejemplo  algo  mas  complejo  de  expresiones.  Por  ejemplo,  considera  la  siguiente 
funcion: 

function  foo  ()  { 

return  5; 

} 


Suponiendo  que  estes  familiarizado  con  el  concepto  de  funciones  (si  no  lo  estas  echale  un  vistazo  al 
capitulo  sobre  funciones),  asumiras  que  teclear  $c  =  foo  ( )  es  esencialmente  lo  mismo  que  escribir  $c 
=  5,  y  has  acertado.  Las  funciones  son  expresiones  que  valen  el  valor  que  retornan.  Como  foo()  devuelve 
5,  el  valor  de  la  expresion  ’foo()’  es  5.  Normalmente  las  funciones  no  devuelven  un  valor  fijo,  sino  que 
suele  ser  calculado. 

Desde  luego,  los  valores  en  PHP  no  se  limitan  a  enteros,  y  lo  mas  normal  es  que  no  lo  sean.  PHP  soporta 
tres  tipos  escalares:  enteros,  punto  flotante  y  cadenas  (los  tipos  escalares  son  aquellos  cuyos  valores  no 
pueden  ’dividirse’  en  partes  menores,  no  como  los  arrays,  por  ejemplo).  PHP  tambien  soporta  dos  tipos 
compuestos  (no  escalares):  arrays  y  objetos.  Se  puede  asignar  cada  uno  de  estos  tipos  de  valor  a  variables 
o  bien  retornarse  de  funciones,  sin  ningun  tipo  de  limitation. 

Hasta  aqui,  los  usuarios  de  PHP/FI  2  no  deberfan  haber  notado  ningun  cambio.  Sin  embargo,  PHP  lleva 
las  expresiones  mucho  mas  alia,  al  igual  que  otros  lenguajes.  PHP  es  un  lenguaje  orientado  a 
expresiones,  en  el  sentido  de  que  casi  todo  es  una  expresion.  Considera  el  ejemplo  anterior  ’$a  =  5’.  Es 
sencillo  ver  que  hay  dos  valores  involucrados,  el  valor  de  la  constante  entera  ’5’,  y  el  valor  de  $a  que  esta 
siendo  actualizado  tambien  a  5.  Pero  la  verdad  es  que  hay  un  valor  adicional  implicado  aqul,  y  es  el  valor 
de  la  propia  asignacion.  La  asignacion  misma  se  evalua  al  valor  asignado,  en  este  caso  5.  En  la  practica, 
quiere  decir  que  ’$a  =  5’,  independientemente  de  lo  que  hace,  es  una  expresion  con  el  valor  5.  De  esta 
manera,  escribir  algo  como  ’$b  =  ($a  =  5)’  es  como  escribir  ’$a  =  5;  $b  =  5;’  (un  punto  y  coma  marca  el 
final  de  una  instruccion).  Como  las  asignaciones  se  evaluan  de  derecha  a  izquierda,  puedes  escribir 
tambien  ’$b  =  $a  =  5’. 

Otro  buen  ejemplo  de  orientation  a  expresiones  es  el  pre  y  post  incremento  y  decremento.  Los  usuarios 
de  PHP/FI  2  y  los  de  otros  muchos  lenguajes  les  sonara  la  notation  variable++  y  variable—.  Esto  son  las 
operaciones  de  incremento  y  decremento.  En  PHP/FI  2,  la  instruccion  ’$a++’  no  tiene  valor  (no  es  una 
expresion),  y  no  puedes  asignarla  o  usarla  de  ningun  otro  modo.  PHP  mejora  las  caracterfsticas  del 
incremento/decremento  haciendolos  tambien  expresiones,  como  en  C.  En  PHP,  como  en  C,  hay  dos  tipos 
de  incremento  -  pre -incremento  y  post-incremento.  Ambos,  en  esencia,  incrementan  la  variable  y  el 
efecto  en  la  variable  es  identico.  La  diferencia  radica  en  el  valor  de  la  propia  expresion  incremento.  El 
preincremento  ,  escrito  ’++$variable’,  se  evalua  al  valor  incrementado  (PHP  incrementa  la  variable  antes 
de  leer  su  valor,  de  ah!  el  nombre  ’preincremento’).  El  postincremento,  escrito  ’$variable++’,  se  evalua  al 
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valor  original  de  $variable  antes  de  realizar  el  incremento  (PHP  incrementa  la  variable  despues  de  leer  su 
valor,  de  ahf  el  nombre  ’postincremento’). 

Un  tipo  muy  corriente  de  expresiones  son  las  expresiones  de  comparacion.  Estas  expresiones  se  evaluan 
a  0  o  1,  significando  FALSO  (false)  o  CIERTO  (true),  respectivamente.  PHP  soporta  >  (mayor  que), 
>=  (mayor  o  igual  que),  ==  (igual  que),  !=  (distinto),  <  (menor  que)  y  <=  (menor  o  igual  que).  Estas 
expresiones  se  usan  frecuentemente  dentro  de  la  ejecucion  condicional  como  la  instruction  if. 

El  ultimo  tipo  de  expresiones  que  trataremos,  es  la  combination  operador-asignacion.  Ya  sabes  que  si 
quieres  incremental'  $a  en  1,  basta  con  escribir  ’$a++'  o  ++$a’.  Pero  que  pasa  si  quieres  anadir  mas  de  1, 
por  ejemplo  3?  Podrfas  escribir  ’$a++’  multiples  veces,  pero  no  es  una  forma  de  hacerlo  ni  eficiente  ni 
comoda.  Una  practica  mucho  mas  corriente  es  escribir  ’$a  =  $a  +  3’.  ’$a  +  3’  se  evalua  al  valor  de  $a  mas 
3,  y  se  asigna  de  nuevo  a  $a,  lo  que  resulta  en  incremental'  $a  en  3.  En  PHP,  como  en  otros  lenguajes 
como  C,  puedes  escribir  esto  de  una  forma  mas  concisa,  que  con  el  tiempo  sera  mas  clara  y  tambien  facil 
de  entender.  Anadir  3  al  valor  actual  de  $a  se  puede  escribir  como  ’$a  +=  3’.  Esto  quiere  decir 
exactamente  "toma  el  valor  de  $a,  sumale  3,  y  asfgnalo  otra  vez  a  $a".  Ademas  de  ser  mas  corto  y  claro, 
tambien  resulta  en  una  ejecucion  mas  rapida.  El  valor  de  ’$a  +=  3’,  como  el  valor  de  una  asignacion 
normal  y  corriente,  es  el  valor  asignado.  Ten  en  cuenta  que  NO  es  3,  sino  el  valor  combinado  de  $a  mas  3 
(ese  es  el  valor  asignado  a  $a).  Cualquier  operation  binaria  puede  ser  usada  en  forma  de 
operador-asignacion,  por  ejemplo  ’$a  -=  5’  (restar  5  del  valor  de  $a),  ’$b  *=  7’  (multiplicar  el  valor  de  $b 
por  5),  etc. 

Hay  otra  expresion  que  puede  parecer  extrana  si  no  la  has  visto  en  otros  lenguaes,  el  operador 
condicional  temario: 


$first  ?  $second  :  $third 

Si  el  valor  de  la  primera  subexpresion  es  verdadero  (distinto  de  cero),  entonces  se  evalua  la  segunda 
subexpresion,  si  no,  se  evalua  la  tercera  y  ese  es  el  valor. 

El  siguiente  ejemplo  te  ayudara  a  comprender  un  poco  mejor  el  pre  y  post  incremento  y  las  expresiones 
en  general: 


function  double ($i) 
return  $i*2; 

} 

$b  =  $a  =  5; 

$c  =  $a++; 

$e  =  $d  =  ++$b; 


{ 


/*  asignar  el  valor  cinco  a  las  variables  $a  y  $b  */ 

/*  postincremento,  asignar  el  valor  original  de  $a  (5)  a  $c  */ 
/*  preincremento,  asignar  el  valor  incrementado  de  $b  (6)  a 
$d  y  a  $e  */ 


/*  en  este  punto,  tanto  $d  como  $e  son  iguales  a  6  */ 


$f  =  double ($d++) ;  /*  asignar  el  doble  del  valor  de  $d  antes 

del  incremento,  2*6  =  12  a  $f  */ 

$g  =  double (++$e) ;  /*  asignar  el  doble  del  valor  de  $e  despues 

del  incremento,  2*7  =  14  a  $g  */ 

$h  =  $g  +=  10;  /*  primero,  $g  es  incrementado  en  10  y  termina  valiendo  24. 

despues  el  valor  de  la  asignacion  (24)  se  asigna  a  $h, 
y  $h  tambien  acaba  valiendo  24.  */ 
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A1  principio  del  capitulo  hemos  dicho  que  describirfamos  los  distintos  tipos  de  instrucciones  y,  como 
prometimos,  las  expresiones  pueden  ser  instrucciones.  Sin  embargo,  no  todas  las  expresiones  son 
instrucciones.  En  este  caso,  una  instruccion  tiene  la  forma  ’expr’  es  decir,  una  expresion  seguida  de 
un  punto  y  coma.  En  ’$b=$a=5;\  $a=5  es  una  expresion  valida,  pero  no  es  una  instruccion  en  si  misma. 
Por  otro  lado  ’$b=$a=5:’  si  es  una  instruccion  valida. 

Una  ultima  cosa  que  vale  la  pena  mencionar,  es  el  valor  booleano  de  las  expresiones.  En  muchas 
ocasiones,  principalmente  en  condicionales  y  bucles,  no  estas  interesado  en  el  valor  exacto  de  la 
expresion,  sino  unicamente  si  es  CIERTA  (true)  o  FALSA  (false)  (PHP  no  tiene  un  tipo  booleano 
especffico).  El  valor  de  verdad  de  las  expresiones  en  PHP  se  calcula  de  forma  similar  a  perl.  Cualquier 
valor  numerico  distinto  de  cero  es  CIERTO  (true),  cero  es  FALSO  (false).  Fljate  en  que  los  valores 
negativos  son  distinto  de  cero  y  considerados  CIERTO  (true)!  La  cadena  vacfa  y  la  cadena  "0"  son 
FALSO  (false);  todas  las  demas  cadenas  son  true.  Con  los  tipos  no  escalares  (arrays  y  objetos)  -  si  el 
valor  no  contiene  elementos  se  considera  FALSO  (false),  en  caso  contrario  se  considera  CIERTO 
(true). 

PHP  te  brinda  una  completa  y  potente  implementacion  de  expresiones,  y  documentarla  enteramente  esta 
mas  alia  del  objetivo  de  ete  manual.  Los  ejemplos  anteriores,  deberfan  darte  una  buena  idea  de  que  son 
las  expresiones  y  como  construir  expresiones  utiles.  A  lo  largo  del  resto  del  manual,  escribiremos  expr 
para  indicar  una  expresion  PHP  valida. 
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Operadores  Aritmeticos 

6Recuerdas  la  aritmetica  basica  del  colegio?  Pues  estos  operadores  funcionan  exactamente  igual. 


Tabla  10-1.  Operadores  Aritmeticos 


ejemplo 

nombre 

resultado 

$a  +  $b 

Adicion 

Suma  de  $a  y  $b. 

$a  -  $b 

Substraccion 

Diferencia  entre  $a  y  $b. 

$a*$b 

Multiplication 

Producto  de  $a  and  $b. 

$a/$b 

Division 

Cociente  de  $a  entre  $b. 

$a  %  $b 

Modulo 

Resto  de  $a  dividido  entre  $b. 

Operadores  de  Asignacion 

El  operador  basico  de  asignacion  es  A  primera  vista  podrias  pensar  que  es  el  operador  de 

comparacion  "igual  que".  Pero  no.  Realmente  significa  que  el  operando  de  la  izquierda  toma  el  valor  de 
la  expresion  a  la  derecha,  (esto  es,  "toma  el  valor  de"). 

El  valor  de  una  expresion  de  asignacion  es  el  propio  valor  asignado.  Esto  es,  el  valor  de  "$a  =  3"  es  3. 
Esto  permite  hacer  cosas  curiosas  como 

$a  =  ($b  =4)  +5;  //  ahora  $a  es  igual  a  9,  y  $b  vale  4. 


Ademas  del  operador  basico  de  asignacion,  existen  los  "operadores  combinados"  para  todas  las 
operaciones  aritmeticas  y  de  cadenas  que  sean  binarias.  Este  operador  combinado  te  permite,  de  una  sola 
vez,  usar  una  variable  en  una  expresion  y  luego  establecer  el  valor  de  esa  variable  al  resultado  de  la 
expresion.  Por  ejemplo: 

$a  =  3; 

$a  +=  5;  //  establece  $a  a  8,  como  si  hubiesemos  escrito:  $a  =  $a  +  5; 

$b  =  "Hola  " ; 

$b  .=  "Ahi!";  //  establece  $b  a  "Hola  Ahi!",  igual  que  si  hiciesemos  $b  =  $b  . 


Ffjate  en  que  la  asignacion  realiza  una  nueva  copia  de  la  variable  original  (asignacion  por  valor),  por  lo 
que  cambios  a  la  variable  original  no  afectan  a  la  copia.  Esto  puede  tener  interes  si  necesitas  copiar  algo 
como  un  array  con  muchos  elementos  dentro  de  un  buck  que  se  repita  muchas  veces  (cada  vez  se 
realizara  una  nueva  copia  del  array).  PHP4  soporta  asignacion  por  referenda,  usando  la  sintaxis  $var  = 
&$othervar; ,  pero  esto  no  es  posible  en  PHP3.  ’Asignacion  por  referencia’  quiere  decir  que  ambas 
variables  acabaran  apuntando  al  mismo  dato  y  que  nada  es  realmente  copiado. 


"Ahi ! " 
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Operadores  Bit  a  bit 

Los  operadores  bit  a  bit  te  permiten  activar  o  desactivar  bits  individuales  de  un  entero. 


Tabla  10-2.  Operadores  Bit  a  bit 


ejemplo 

nombre 

resultado 

$a  &  $b 

Y 

Se  activan  los  bits  que  estan 
activos  tanto  en  $a  como  $b. 

$a  1  $b 

0 

Se  activan  los  bits  que  estan 
activos  en  $a  o  que  lo  estan  en  $b. 

$aA$b 

Xor  ("o  exclusiva") 

Se  activan  los  bits  que  estan 
activos  en  $a  o  en  $b  pero  no  en 
ambos  a  la  vez. 

~  $a 

No 

Se  activan  los  bits  que  no  estan 
activos  en  $a. 

$a  «  $b 

Desplazamiento  a  la  izquierda 

Desplaza  los  bits  de  $a,  $b 
posiciones  hacia  la  izquierda  (por 
aritmetica  binaria,  cada  posicion 
desplazada  equivale  a  multiplicar 
por  dos  el  valor  de  $a) 

$a  »  $b 

Desplazamiento  a  la  derecha 

Desplaza  los  bits  de  $a,  $b 
posiciones  hacia  la  derecha  (por 
aritmetica  binaria,  cada  posicion 
desplazada  equivale  a  dividir  entre 
dos  el  valor  de  $a) 

Operadores  de  Comparacion 

Los  operadores  de  comparacion,  como  su  nombre  indica,  permiten  comparar  dos  valores. 


Tabla  10-3.  Operadores  de  Comparacion 


ejemplo 

nombre 

resultado 

& 

P 

II 

II 

CT 

Igualdad 

Cierto  si  $a  es  igual  a  $b. 

$a  ===  $b 

Identidad 

Cierto  si  $a  es  igual  a  $b  y  si  son 
del  mismo  tipo  (solo  PHP4) 

$a  !=  $b 

Desigualdad 

Cierto  si  $a  no  es  igual  a  $b. 

$a  <  $b 

Menor  que 

Cierto  si  $a  es  estrictamente 
menor  que  $b. 

$a  >  $b 

Mayor  que 

Cierto  si  $a  es  estrictamente 
mayor  que  $b. 
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ejemplo 

nombre 

resultado 

$a  <=  $b 

Menor  o  igual  que 

Cierto  si  $a  es  menor  o  igual  que 
$b. 

$a  >=  $b 

Mayor  o  igual  que 

Cierto  si  $a  es  mayor  o  igual  que 
$b. 

Otro  operador  condicional  es  el  operador  (o  ternario),  que  funciona  como  en  C  y  otros  muchos 
lenguajes. 


(exprl)  ?  (expr2)  :  (expr3) ; 

La  expresion  toma  el  valor  expr2  si  exprl  se  evalua  a  cierto,  y  expr3  si  exprl  se  evalua  a  falso. 


Operador  de  ejecucion 

PHP  soporta  un  operador  de  ejecucion:  el  apostrofe  invertido  (“).  jFfjate  que  no  son  apostrofes  normales! 
PHP  intentara  ejecutar  la  instruction  contenida  dentro  de  los  apostrofes  invertidos  como  si  fuera  un 
comando  del  shell;  y  su  salida  devuelta  como  el  valor  de  esta  expresion  (i.e.,  no  tiene  por  que  ser 
simplemente  volcada  como  salida;  puede  asignarse  a  una  variable). 

$output  =  'Is  -al'; 

echo  "<pre>$output</pre>" ; 


Ver  tambien  system'),  passthru'),  exec'),  popen3,  y  escapeshellcmd  ). 


Operadores  de  Incremento/decremento 

PHP  soporta  los  operadores  de  predecremento  y  post  incremento  al  estilo  de  C. 


Tabla  10-4.  Operadores  de  Incremento/decremento 


ejemplo 

nombre 

efecto 

-i-+$a 

Preincremento 

Incrementa  $a  en  uno  y  despues 
devuelve  $a. 

$a++ 

Postincremento 

Devuelve  $a  y  despues  incrementa 
$a  en  uno. 

-$a 

Predecremento 

Decrementa  $a  en  uno  y  despues 
devuelve  $a. 

$a~ 

Postdecremento 

Devuelve  $a  y  despues  decrementa 
$a  en  uno. 
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He  aquf  un  listado  de  ejemplo: 


<?php 

echo  "<h3>Postincremento</h3>" ; 

$a  =  5; 

echo  "Deberia  ser  5:  "  .  $a++  .  "<br>\n"; 

echo  "Deberia  ser  6:  "  .  $a  .  "<br>\n"; 

echo  "<h3>Preincremento</h3>" ; 

$a  =  5; 

echo  "Deberia  ser  6:  "  .  ++$a  .  "<br>\n"; 

echo  "Deberia  ser  6:  "  .  $a  .  "<br>\n"; 

echo  "<h3>Postdecremento</h3>" ; 

$a  =  5; 

echo  "Deberia  ser  5:  "  .  $a —  .  "<br>\n"; 

echo  "Deberia  ser  4:  "  .  $a  .  "<br>\n"; 

echo  "<h3>Predecremento</h3>" ; 

$a  =  5; 

echo  "Deberia  ser  4:  "  .  — $a  .  "<br>\n"; 

echo  "Deberia  ser  4:  "  .  $a  .  "<br>\n"; 

?> 


Operadores  Logicos 


Tabla  10-5.  Operadores  Logicos 


ejemplo 

nombre 

resultado 

$a  and  $b 

Y 

Cierto  si  tanto  $a  como  $b  son 
ciertos. 

$a  or  $b 

0 

Cierto  si  $a  o  $b  son  ciertos. 

$a  xor  $b 

0  exclusiva 

Cierto  si  $a  es  cierto  o  $b  es  cierto, 
pero  no  ambos  a  la  vez. 

!  $a 

Negation 

Cierto  si  $a  no  es  cierto. 

$a  &&  $b 

Y 

Cierto  si  tanto  $a  como  $b  son 
ciertos. 

$a  II  $b 

0 

Cierto  si  $a  o  $b  son  ciertos. 

La  razon  de  las  dos  variaciones  de  "y"  y  "o"  es  que  operan  con  distinta  precedencia  (ver  Precedencia  de 
Operadores ) 
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Precedencia  de  Operadores 

La  precedencia  de  operadores  especifica  como  se  agrupan  las  expresiones.  Por  ejemplo,  en  la  expresion  1 
+  5  *  3,  la  respuesta  es  16  y  no  18  porque  el  operador  de  multiplicacion  ("*")  tiene  una  mayor 
precedencia  que  el  de  adicion  ("+"). 

La  siguiente  tabla  lista  la  precedencia  de  operadores,  indicandose  primero  los  de  menor  precedencia. 


Tabla  10-6.  Precedencia  de  Operadores 


Asociatividad 

Operadores 

izquierda 

izquierda 

or 

izquierda 

xor 

izquierda 

and 

derecha 

print 

izquierda 

=  +=  -=  *=  /=  .=  %=  &=  1=  A=  ~=  «=  »= 

izquierda 

?  : 

izquierda 

ii 

izquierda 

&& 

izquierda 

izquierda 

A 

izquierda 

& 

no  asociativo 

==  !=  === 

no  asociativo 

<<=>>= 

izquierda 

«  » 

izquierda 

+ - . 

izquierda 

*/% 

derecha 

!  -  -H —  (int)  (double)  (string)  (array)  (object)  @ 

derecha 

1 

no  asociativo 

new 

Operadores  de  Cadenas 

Hay  dos  operadores  de  cadenas.  El  primero  es  el  operador  de  concatenacion  que  devuelve  el 
resultado  de  concatenar  sus  operandos  izquierdo  y  derecho.  El  segundo  es  el  operador  de  concatenacion 
y  asignacion  (’.=’).  Consulta  Operadores  de  Asignacion  para  mas  information. 

$a  =  "Hola  " ; 

$b  =  $a  .  "Mundo!";  //  ahora  $b  contiene  "Hola  Mundo ! " 
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$a  =  "Hola  " ; 

$a  .=  "Mundo!";  //  ahora  $a  contiene  "Hola  Mundo ! " 
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Todo  archivo  de  comandos  PHP  se  compone  de  una  serie  de  sentencias.  Una  sentencia  puede  ser  una 
asignacion,  una  llamada  a  funcion,  un  buck,  una  sentencia  condicional  e  incluso  una  sentencia  que  no 
haga  nada  (una  sentencia  vacfa).  Las  sentencias  normalmente  acaban  con  punto  y  coma.  Ademas,  las 
sentencias  se  pueden  agrupar  en  grupos  de  sentencias  encapsulando  un  grupo  de  sentencias  con  Haves. 
Un  grupo  de  sentencias  es  tambien  una  sentencia.  En  este  capttulo  se  describen  los  diferentes  tipos  de 
sentencias. 


if 


La  construccion  if  es  una  de  las  mas  importantes  caracterfsticas  de  muchos  lenguajes,  incluido  PHP. 
Permite  la  ejecucion  condicional  de  fragmentos  de  codigo.  PHP  caracteriza  una  estructura  if  que  es 
similar  a  la  de  C: 


if  (expr) 

sentencia 


Como  se  describe  en  la  section  sobre  expresiones,  expr  se  evalua  a  su  valor  condicional.  Si  expr  se 
evalua  como  true,  PHP  ejecutara  la  sentencia,  y  si  se  evalua  como  false  -  la  ignorara. 

El  siguiente  ejemplo  mostrana  a  es  mayor  que  b  si  $a  fuera  mayor  que  $b: 

if  ($a  >  $b) 

print  "a  es  mayor  que  b"; 


A  menudo,  se  desea  tener  mas  de  una  sentencia  ejecutada  de  forma  condicional.  Por  supuesto,  no  hay 
necesidad  de  encerrar  cada  sentencia  con  una  clausula  if.  En  vez  de  eso,  se  pueden  agrupar  varias 
sentencias  en  un  grupo  de  sentencias.  Por  ejemplo,  este  codigo  mostrana  a  es  mayor  que  b  si  $a 
fuera  mayor  que  $b,  y  entonces  asignarfa  el  valor  de  $a  a  $b: 

if  ($a  >  $b)  { 

print  "a  es  mayor  que  b"; 

$b  =  $a; 

} 


Las  sentencias  if  se  pueden  anidar  indefinidamente  dentro  de  otras  sentencias  i  f ,  lo  cual  proporciona 
una  flexibilidad  completa  para  ejecuciones  condicionales  en  las  diferentes  partes  de  tu  programa. 
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else 


A  menudo  queremos  ejecutar  una  sentencia  si  se  cumple  una  cierta  condicion,  y  una  sentencia  distinta  si 
la  condicion  no  se  cumple.  Esto  es  para  lo  que  sirve  else,  else  extiende  una  sentencia  if  para  ejecutar 
una  sentencia  en  caso  de  que  la  expresion  en  la  sentencia  if  se  evalue  como  false.  Por  ejemplo,  el 
siguiente  codigo  mostrana  a  es  mayor  que  b  si  $a  fuera  mayor  que  $b,  y  a  NO  es  mayor  que  b 
en  cualquier  otro  caso: 

if  ($a  >  $b)  { 

print  "a  es  mayor  que  b"; 

}  else  { 

print  "a  NO  es  mayor  que  b"; 

} 


La  sentencia  else  se  ejecuta  solamente  si  la  expresion  if  se  evalua  como  false,  y  si  hubiera  alguna 
expresion  elseif  -  solo  si  se  evaluaron  tambien  a  false  (Ver  elseif). 


elseif 

elseif,  como  su  nombre  sugiere,  es  una  combination  de  if  y  else.  Como  else,  extiende  una 
sentencia  i  f  para  ejecutar  una  sentencia  diferente  en  caso  de  que  la  expresion  i  f  original  se  evalua  como 
false.  No  obstante,  a  diferencia  de  else,  ejecutara  esa  expresion  alternativa  solamente  si  la  expresion 
condicional  elseif  se  evalua  como  true.  Por  ejemplo,  el  siguiente  codigo  mostrana  a  es  mayor 
que  b, a  es  igual  a  b  o  a  es  menor  que  b: 


if  ($a  >  $b)  { 

print  "a  es 
}  elseif  ($a  == 
print  "a  es 
}  else  { 

print  "a  es 

} 


mayor  que  b"; 
$b)  { 

igual  que  b"; 
mayor  que  b"; 


Puede  haber  varios  elseifs  dentro  de  la  misma  sentencia  if.  La  primera  expresion  elseif  (si  hay 
alguna)  que  se  evalue  como  true  se  ejecutarfa.  En  PHP,  tambien  se  puede  escribir  ’else  if’  (con  dos 
palabras)  y  el  comportamiento  serfa  identico  al  de  un  ’elseif’  (una  sola  palabra).  El  significado  sintactico 
es  ligeramente  distinto  (si  estas  familiarizado  con  C,  es  el  mismo  comportamiento)  pero  la  h'nea  basica  es 
que  ambos  resultanan  tener  exactamente  el  mismo  comportamiento. 

La  sentencia  elseif  se  ejecuta  solo  si  la  expresion  if  precedente  y  cualquier  expresion  elseif 
precedente  se  evaluan  como  false,  y  la  expresion  elseif  actual  se  evalua  como  true. 
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Sintaxis  Alternativa  de  Estructuras  de  Control 


PHP  ofrece  una  sintaxis  altenativa  para  alguna  de  sus  estructuras  de  control;  a  saber,  if,  while,  for,  y 
switch.  En  cada  caso,  la  forma  basica  de  la  sintaxis  alternativa  es  cambiar  abrir-llave  por  dos  puntos  (:) 
y  cerrar-llave  por  endif ; ,  endwhile; ,  endfor ; ,  or  endswitch; ,  respectivamente. 


<?php  if  ($a==5) :  ?> 
A  es  igual  a  5 
<?php  endif;  ?> 


En  el  ejemplo  de  arriba,  el  bloque  HTML  "A  =  5"  se  anida  dentro  de  una  sentencia  if  escrita  en  la 
sintaxis  alternativa.  El  bloque  HTML  se  mostrana  solamente  si  $a  fuera  igual  a  5. 

La  sintaxis  alternativa  se  aplica  a  else  y  tambien  a  el  seif.  La  siguiente  es  una  estructura  if  con 
elseifyelseenel  formato  alternativo: 

if  ($a  ==  5) : 

print  "a  es  igual  a  5"; 
print 

elseif  ($a  ==  6) : 

print  "a  es  igual  a  6"; 
print  "!!!"; 
else : 

print  "a  no  es  ni  5  ni  6"; 
endif; 


Mirar  tambien  while  for  e  if  para  mas  ejemplos. 


while 

Los  bucles  while  son  los  tipos  de  bucle  mas  simples  en  PHP.  Se  comportan  como  su  contrapartida  en  C. 
La  forma  basica  de  una  sentencia  while  es: 

while  (expr)  sentencia 


El  significado  de  una  sentencia  while  es  simple.  Le  dice  a  PHP  que  ejecute  la(s)  sentencia(s)  anidada(s) 
repetidamente,  mientras  la  expresion  while  se  evalue  como  true.  El  valor  de  la  expresion  es 
comprobado  cada  vez  al  principio  del  bucle,  asf  que  incluso  si  este  valor  cambia  durante  la  ejecucion  de 
la(s)  sentencia(s)  anidada(s),  la  ejecucion  no  parara  hasta  el  fin  de  la  iteracion  (cada  vez  que  PHP  ejecuta 
las  sentencias  en  el  bucle  es  una  iteracion).  A  veces,  si  la  expresion  while  se  evalua  como  false  desde 
el  principio  de  todo,  la(s)  sentencia(s)  anidada(s)  no  se  ejecutaran  ni  siquiera  una  vez. 
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Como  con  la  sentencia  if,  se  pueden  agrupar  multiples  sentencias  dentro  del  mismo  bucle  while 
encerrando  un  grupo  de  sentencias  con  Haves,  o  usando  la  sintaxis  alternativa: 

while  (expr) :  sentencia  . . .  endwhile; 


Los  siguientes  ejemplos  son  identicos,  y  ambos  imprimen  numeros  del  1  al  10: 

/*  ejemplo  1  */ 

$  i  =  1  ; 

while  ($i  <=  10)  { 

print  $i++;  /*  el  valor  impreso  seria 

$i  antes  del  incremento 
(post-incremento)  */ 

} 

/*  ejemplo  2  */ 

$i  =  1; 

while  ( $i  <=  10 ) : 
print  $i; 

$  i++ ; 
endwhile; 


do . .while 

Los  bucles  do .  .  while  son  muy  similares  a  los  bucles  while,  excepto  que  las  condiciones  se 
comprueban  al  final  de  cada  iteracion  en  vez  de  al  principio.  La  principal  diferencia  frente  a  los  bucles 
regulares  while  es  que  se  garantiza  la  ejecucion  de  la  primera  iteracion  de  un  bucle  do .  .while  (la 
condicion  se  comprueba  solo  al  final  de  la  iteracion),  mientras  que  puede  no  ser  necesariamente 
ejecutada  con  un  bucle  while  regular  (la  condicion  se  comprueba  al  principio  de  cada  iteracion,  si  esta 
se  evalua  como  false  desde  el  principio  la  ejecucion  del  bucle  finalizara  inmediatamente). 

Hay  una  sola  sintaxis  para  los  bucles  do .  .while: 

$i  =  0; 
do  { 

print  $i; 

}  while  ($i>0) ; 
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El  buck  de  arriba  se  ejecutarfa  exactamente  una  sola  vez,  despues  de  la  primera  iteracion,  cuando  la 
condicion  se  comprueba,  se  evalua  como  false  ($i  no  es  mas  grande  que  0)  y  la  ejecucion  del  bucle 
finaliza. 

Los  usuarios  avanzados  de  C  pueden  estar  familiarizados  con  un  uso  distinto  del  bucle  do .  .  while,  para 
permitir  parar  la  ejecucion  en  medio  de  los  bloques  de  codigo,  encapsulandolos  con  do .  .  while(O),  y 
usando  la  sentencia  break  El  siguiente  fragmento  de  codigo  demuestra  esto: 

do  { 

if  ( $i  <  5)  { 

print  "i  no  es  lo  suf icientemente  grande"; 
break; 

} 

$i  *=  $factor; 
if  ($i  <  $minimum_limit )  { 

break; 

} 

print  "i  es  correcto"; 

. . . procesa  i . .  . 

}  while ( 0 )  ; 


No  se  preocupes  si  no  entiende  esto  completamente  o  en  absoluto.  Se  pueden  codificar  archivos  de 
comandos  e  incluso  archivos  de  comandos  potentes  sin  usar  esta  ’propiedad’. 


for 

Los  bucles  for  son  los  bucles  mas  complejos  en  PHP.  Se  comportan  como  su  contrapartida  en  C.  La 
sintaxis  de  un  bucle  for  es: 

for  (exprl;  expr2;  expr3)  sentencia 


La  primera  expresion  (exprl)  se  evalua  (ejecuta)  incondicionalmente  una  vez  al  principio  del  bucle. 

A1  comienzo  de  cada  iteracion,  se  evalua  expr2  .  Si  se  evalua  como  true,  el  bucle  continua  y  las 
sentencias  anidadas  se  ejecutan.  Si  se  evalua  como  false,  la  ejecucion  del  bucle  finaliza. 

Al  final  de  cada  iteracion,  se  evalua  (ejecuta)  expr3. 

Cada  una  de  las  expresiones  puede  estar  vacfa.  Que  expr2  este  vacfa  significa  que  el  bucle  deberfa 
correr  indefinidamente  (PHP  implicitamente  lo  considera  como  true,  al  igual  que  C).  Esto  puede  que  no 
sea  tan  inutil  como  se  podrfa  pensar,  puesto  que  a  menudo  se  quiere  salir  de  un  bucle  usando  una 
sentencia  break  condicional  en  vez  de  usar  la  condicion  de  for. 

Considera  los  siguientes  ejemplos.  Todos  ellos  muestran  numeros  del  1  al  10: 

/*  ejemplo  1  */ 
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for  ($i  =  1;  $i  <=  10;  $i++)  { 

print  $i; 

} 

/*  ejemplo  2  */ 

for  ($i  =  1; ; $i++)  { 

if  ( $i  >  10)  { 

break; 

} 

print  $i; 

} 

/*  ejemplo  3  */ 

$  i  =  1  ; 
for  (;;)  { 

if  ( $i  >  10)  { 

break; 

} 

print  $i; 

$  i++  ; 

} 

/*  ejemplo  4  */ 

for  ($i  =  1;  $i  <=  10;  print  $i,  $i++)  ; 


Por  supuesto,  el  primer  ejemplo  parece  ser  el  mas  elegante  (o  quizas  el  cuarto),  pero  uno  puede  descubrir 
que  ser  capaz  de  usar  expresiones  vaclas  en  bucles  for  resulta  util  en  muchas  ocasiones. 

PHP  tambien  soporta  la  "sintaxis  de  dos  puntos"  alternativa  para  bucles  for. 
for  (exprl;  expr2;  expr3) :  sentencia;  .  ..;  endfor; 


Otros  lenguajes  poseen  una  sentencia  f  oreach  para  traducir  un  array  o  una  tabla  hash.  PHP3  no  posee 
tal  construccion;  PHP4  si  (ver  foreach).  En  PHP3,  se  puede  combinar  while  con  las  funciones  list  j  y 
each')  para  conseguir  el  mismo  efecto.  Mirar  la  documentacion  de  estas  funciones  para  ver  un  ejemplo. 
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foreach 

PHP4  (PHP3  no)  incluye  una  construccion  foreach,  tal  como  perl  y  algunos  otros  lenguajes.  Esto 
simplemente  da  un  modo  facil  de  iterar  sobre  arrays.  Hay  dos  sintaxis;  la  segunda  es  una  extension 
menor,  pero  util  de  la  primera: 


foreach (expresion_array  as  $value)  sentencia 
foreach (expresion_array  as  $key  =>  $value)  sentencia 


La  primera  forma  recorre  el  array  dado  por  expresion_array.  En  cada  iteracion,  el  valor  del  elemento 
actual  se  asigna  a  $value  y  el  puntero  interno  del  array  se  avanza  en  una  unidad  (asf  en  el  siguiente 
paso,  se  estara  mirando  el  elemento  siguiente). 

La  segunda  manera  hace  lo  mismo,  salvo  que  la  clave  del  elemento  actual  sera  asignada  a  la  variable 
$key  en  cada  iteracion. 


Nota:  Cuando  foreach  comienza  su  primera  ejecucion,  el  puntero  interno  a  la  lista  (array)  se 
reinicia  automaticamente  al  primer  elemento  del  array.  Esto  significa  que  no  se  necesita  llamar  a 
reset;)  antes  de  un  bucle  foreach. 


Nota:  Hay  que  tener  en  cuanta  queforeach  con  una  copia  de  la  lista  (array)  especificada  y  no  la 
lista  en  si,  por  ello  el  puntero  de  la  lista  no  es  modificado  como  en  la  construccion  each. 


Puede  haber  observado  que  las  siguientes  son  funcionalidades  identicas: 

reset (  $arr  )  ; 

while  (  list  (  ,  $value  )  =  each  (  $arr  )  )  { 

echo  "Valor:  $value<br>\n" ; 

} 

foreach  (  $arr  as  $value  )  { 

echo  "Valor:  $value<br>\n" ; 

} 


Las  siguientes  tambien  son  funcionalidades  identicas: 

reset (  $arr  )  ; 

while (  list (  $key,  $value  )  =  each (  $arr  )  )  { 

echo  "Key:  $key;  Valor:  $value<br>\n" ; 

} 
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foreach  (  $arr  as  $key  =>  $value  )  { 

echo  "Key:  $key;  Valor:  $value<br>\n" ; 

} 


Algunos  ejemplos  mas  para  demostrar  su  uso: 

/*  foreach  ejemplo  1:  solo  valor*/ 

$a  =  array  (1,  2,  3,  17); 

foreach ($a  as  $v)  { 

print  "Valor  actual  de  \$a:  $v.\n"; 

} 

/*  foreach  ejemplo  2:  valor  (con  clave  impresa  para  ilustrar)  */ 

$a  =  array  (1,  2,  3,  17); 

$i  =  0;  /*  solo  para  propositos  demostrativos  */ 

foreach ($a  as  $v)  { 

print  "\$a[$i]  =>  $k.\n"; 

} 

/*  foreach  ejemplo  3:  clave  y  valor  */ 

$a  =  array ( 

"uno"  =>  1, 

"dos"  =>  2, 

"tres"  =>  3, 

"diecisiete"  =>  17 

)  ; 

foreach ($a  as  $k  =>  $v)  { 

print  " \$a [ $k]  =>  $v.\n"; 

} 


break 


break  escapa  de  la  estructuras  de  control  iterante  (bucle)  actuales  for,  while,  o  switch. 

break  accepta  un  parametro  opcional,  el  cual  determina  cuantas  estructuras  de  control  hay  que  escapar. 

$arr  =  array  ('one',  'two',  'three',  'four',  'stop',  'five'); 
while  (list  (,  $val)  =  each  ($arr) )  { 

if  ($val  ==  'stop')  { 

break;  /*  You  could  also  write  'break  1;'  here.  */ 
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} 

echo  "$val<br>\n" ; 

} 

/*  Using  the  optional  argument.  */ 

$i  =  0; 

while  (++$i)  { 

switch  ($i)  { 

case  5: 

echo  "At  5<br>\n"; 

break  1;  /*  Exit  only  the  switch.  */ 

case  10  : 

echo  "At  10;  quitting<br>\n" ; 

break  2;  /*  Exit  the  switch  and  the  while.  */ 

default : 

break; 


} 


continue 

continue  se  usa  dentro  de  la  estructura  del  bucle  para  saltar  el  resto  de  la  iteration  actual  del  bucle  y 
continuar  la  ejecucion  al  comienzo  de  la  siguiente  iteration. 

continue  accepta  un  parametro  optional,  el  cual  determina  cuantos  niveles  (bluces)  hay  que  saltar  antes 
de  continuar  con  la  ejecucion. 


while  (list ($key, $value)  =  each ($arr) )  { 

if  ($key  %  2)  {  //  salta  los  miembros  impares 

continue ; 

} 

do_something_odd  ($value); 


$i  =  0; 

while  ($i++  <  5)  { 

echo  "Outer<br>\n" ; 
while  (1)  { 

echo  "  Middle<br>\n" ; 
wh i 1 e  ( 1 )  { 

echo  "  Inner<br>\n" ; 
continue  3; 

} 

echo  "This  never  gets  output . <br>\n" ; 

} 

echo  "Neither  does  this . <br>\n" ; 

} 
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switch 

La  sentencia  switch  es  similar  a  una  serie  de  sentencias  IF  en  la  misma  expresion.  En  muchas 
ocasiones,  se  quiere  comparar  la  misma  variable  (o  expresion)  con  nuchos  valores  diferentes,  y  ejecutar 
una  parte  de  codigo  distinta  dependiendo  de  a  que  valor  es  igual.  Para  ello  sirve  la  sentencia  switch. 

Los  siguientes  dos  ejemplos  son  dos  modos  distintos  de  escribir  la  misma  cosa,  uno  usa  una  serie  de 
sentencias  if,  y  el  otro  usa  la  sentencia  switch: 


if 

($i  == 

0) 

{ 

i 

print 

"i 

es 

igual 

a 

0" 

; 

if 

($i  == 

1) 

{ 

i 

print 

"i 

es 

igual 

a 

1" 

; 

if 

($i  == 

2) 

{ 

print 

"i 

es 

igual 

a 

2" 

} 


switch  ( $ i )  { 

case  0  : 

print  "i  es  igual  a  0"; 
break; 
case  1  : 

print  "i  es  igual  a  1"; 
break; 
case  2  : 

print  "i  es  igual  a  2"; 
break; 

} 


Es  importante  entender  como  se  ejecuta  la  sentencia  switch  para  evitar  errores.  La  sentencia  switch 
ejecuta  linea  por  lrnea  (realmente,  sentencia  a  sentencia).  A1  comienzo,  no  se  ejecuta  codigo.  Solo 
cuando  se  encuentra  una  sentencia  case  con  un  valor  que  coincide  con  el  valor  de  la  expresion  switch 
PHP  comienza  a  ejecutar  las  sentencias.  PHP  continua  ejecutando  las  sentencias  hasta  el  final  del  bloque 
switch,  o  la  primera  vez  que  vea  una  sentencia  break.  Si  no  se  escribe  una  sentencia  break  al  final  de 
una  lista  de  sentencias  case,  PHP  seguira  ejecutando  las  sentencias  del  siguiente  case.  Por  ejemplo: 

switch  ( $ i )  { 

case  0  : 

print  "i  es  igual  a  0"; 
case  1  : 

print  "i  es  igual  a  1"; 
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case  2  : 


print 


i  es  igual  a  2"; 


Aquf,  si  $i  es  igual  a  0,  jPHP  ejecutarfa  todas  las  sentecias  print!  Si  $i  es  igual  a  1,  PHP  ejecutarfa  las 
ultimas  dos  sentencias  print  y  solo  si  $i  es  igual  a  2,  se  obtendrfa  la  conducta  ’esperada’  y  solamente  se 
mostrarfa  ’i  es  igual  a  2’.  Asf,  es  importante  no  olvidar  las  sentencias  break  (incluso  aunque  pueda 
querer  evitar  escribirlas  intencionadamente  en  ciertas  circunstancias). 

En  una  sentencia  switch,  la  condicion  se  evalua  solo  una  vez  y  el  resultado  se  compara  a  cada  sentencia 
case.  En  una  sentencia  elseif,  la  condicion  se  evalua  otra  vez.  Si  tu  condicion  es  mas  complicada  que 
una  comparacion  simple  y/o  esta  en  un  bucle  estrecho,  un  switch  puede  ser  mas  rapido. 

La  lista  de  sentencias  de  un  case  puede  tambien  estar  vacfa,  lo  cual  simplemente  pasa  el  control  a  la  lista 
de  sentencias  del  siguiente  case. 

switch  ( $ i )  { 

case  0  : 
case  1  : 
case  2  : 

print  "i  es  menor  que  3,  pero  no  negativo"; 
break; 
case  3  : 

print  "i  es  3"; 

} 


Un  case  especial  es  el  default  case.  Este  case  coincide  con  todo  lo  que  no  coincidan  los  otros  case.  Por 
ejemplo: 


switch  ( $ i )  { 

case  0  : 

print  "i  es  igual  a  0"; 
break; 
case  1  : 

print  "i  es  igual  a  In¬ 
break; 
case  2  : 


print  "i  es  igual  a  2"; 
break; 
default : 

print  "i  no  es  igual  a  0, 

} 


1  o  2"; 
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La  expresion  case  puede  ser  cualquier  expresion  que  se  evalue  a  un  tipo  simple,  es  decir,  numeros 
enteros  o  de  punto  flotante  y  cadenas  de  texto.  No  se  pueden  usar  aquf  ni  arrays  ni  objetos  a  menos  que 
se  conviertan  a  un  tipo  simple. 

La  sintaxis  alternativa  para  las  estructuras  de  control  esta  tambien  soportada  con  switch.  Para  mas 
information,  ver  Sintaxis  alternativa  para  estructuras  de  control 


switch  ( $ i ) : 
case  0  : 

print  "i  es  igual  0"; 
break; 
case  1  : 

print  "i  es  igual  a  1"; 
break; 
case  2  : 

print  "i  es  igual  a  2"; 
break; 
default : 

print  "i  no  es  igual  a  0, 
endswitch; 


1  o  2"; 


require() 

La  sentencia  require  ')  se  sustituye  a  si  misma  con  el  archivo  especificado,  tal  y  como  funciona  la 
directiva  #include  de  C. 

Un  punto  importante  sobre  su  funcionamiento  es  que  cuando  un  archivo  se  incluye  con  include ')  o  se 
requiere  con  require ))),  el  interprete  sale  del  modo  PHP  y  entra  en  modo  HTML  al  principio  del  archivo 
referenciado,  y  vuelve  de  nuevo  al  modo  PHP  al  final.  Por  esta  razon,  cualquier  codigo  dentro  del  archivo 
referenciado  que  debiera  ser  ejecutado  como  codigo  PHP  debe  ser  encerrado  dentro  de  etiquetas  validas 
de  comienzo  y  fin  de  PHP 

require))  no  es  en  realidad  una  funcion  de  PHP;  es  mas  una  construction  del  lenguaje.  Esta  sujeta  a 
algunas  reglas  distintas  de  las  de  funciones.  Por  ejemplo,  require))  no  esta  sujeto  a  ninguna  estructura  de 
control  contenedora.  Por  otro  lado,  no  devuelve  ningun  valor;  intentar  leer  un  valor  de  retorno  de  una 
llamada  a  un  require ))  resulta  en  un  error  del  interprete. 

A  diferencia  de  include)),  require))  siempre  leera  el  archivo  referenciado,  incluso  si  la  llnea  en  que  esta 
no  se  ejecuta  nunca.  Si  se  quiere  incluir  condicionalmente  un  archivo,  se  usa  include)).  La  sentencia 
conditional  no  afecta  a  require)).  No  obstante,  si  la  lfnea  en  la  cual  aparece  el  require))  no  se  ejecuta, 
tampoco  se  ejecutara  el  codigo  del  archivo  referenciado. 

De  forma  similar,  las  estructuras  de  bucle  no  afectan  la  conducta  de  require)).  Aunque  el  codigo 
contenido  en  el  archivo  referenciado  esta  todavfa  sujeto  al  bucle,  el  propio  require))  solo  ocurre  una  vez. 

Esto  significa  que  no  se  puede  poner  una  sentencia  require  ))  dentro  de  una  estructura  de  bucle  y  esperar 
que  incluya  el  contenido  de  un  archivo  distinto  en  cada  iteration.  Para  hacer  esto,  usa  una  sentencia 
include )). 
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require  (  ' header. inc'  ); 


When  a  file  is  require ')ed,  the  code  it  contains  inherits  the  variable  scope  of  the  line  on  which  the 
require')  occurs.  Any  variables  available  at  that  line  in  the  calling  file  will  be  available  within  the  called 
file.  If  the  require;)  occurs  inside  a  function  within  the  calling  file,  then  all  of  the  code  contained  in  the 
called  file  will  behave  as  though  it  had  been  defined  inside  that  function. 

If  the  require))ed  file  is  called  via  HTTP  using  the  fopen  wrappers,  and  if  the  target  server  interprets  the 
target  file  as  PHP  code,  variables  may  be  passed  to  the  require  ))ed  file  using  an  URL  request  string  as 
used  with  HTTP  GET.  This  is  not  strictly  speaking  the  same  thing  as  require  ))ing  the  file  and  having  it 
inherit  the  parent  file’s  variable  scope;  the  script  is  actually  being  run  on  the  remote  server  and  the  result 
is  then  being  included  into  the  local  script. 

/*  This  example  assumes  that  someserver  is  configured  to  parse  .php 

*  files  and  not  .txt  files.  Also,  'works'  here  means  that  the  variables 

*  $varone  and  $vartwo  are  available  within  the  require ( ) ed  file.  */ 

/*  Won't  work;  file.txt  wasn't  handled  by  someserver.  */ 
require  ( "http : / / someserver/ file . txt ?varone=l&vartwo=2 " ) ; 

/*  Won't  work;  looks  for  a  file  named  ' f ile . php?varone=l&vartwo=2 ' 

*  on  the  local  filesystem.  */ 
require  ( " f ile . php?varone=l&vartwo=2 " ) ; 

/ *  Works .  * / 

require  ( "http : / / someserver/ file . php?varone=l&vartwo=2 " ) ; 

$varone  =  1; 

$vartwo  =  2; 

require  ("file.txt");  /*  Works.  */ 
require  (  "file .php" ) ;  /*  Works.  */ 


En  PHP3,  es  posible  ejecutar  una  sentencia  return  dentro  de  un  archivo  referenciado  con  require)),  en 
tanto  en  cuanto  esa  sentencia  aparezca  en  el  ambito  global  del  archivo  requerido  (require))).  No  puede 
aparecer  dentro  de  ningun  bloque  (lo  que  siginifica  dentro  de  llaves({ })).  En  PHP4,  no  obstante,  esta 
capacidad  ha  sido  desestimada.  Si  se  necesita  esta  funcionalidad,  vease  include)). 

Ver  tambien  include  ),  require_once)),  include_once )),  readfile)),  y  virtual)). 


include() 

La  sentencia  include))  incluye  y  evalua  el  archivo  especificado. 

Si  "URL  fopen  wrappers"  esta  activada  en  PHP  (como  esta  en  la  configuration  inicial),  se  puede 
especificar  el  fichero  que  se  va  a  incluir  usando  una  URL  en  vez  de  un  fichero  local  (con  su  Path)  Ver 
Ficheros  remotos  y  fopen ))  para  mas  information. 
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Un  punto  importante  sobre  su  funcionamiento  es  que  cuando  un  archivo  se  incluye  con  include ')  o  se 
requiere  con  require '),  el  interprete  sale  del  modo  PHP  y  entra  en  modo  HTML  al  principio  del  archivo 
referenciado,  y  vuelve  de  nuevo  al  modo  PHP  al  final.  Por  esta  razon,  cualquier  codigo  dentro  del  archivo 
referenciado  que  debiera  ser  ejecutado  como  codigo  PHP  debe  ser  encerrado  dentro  de  etiquetas  validas 
de  comienzo  y  fin  de  PHP 

Esto  sucede  cada  vez  que  se  encuentra  la  sentencia  include  '),  asf  que  se  puede  usar  una  sentencia 
include ')  dentro  de  una  estructura  de  bucle  para  incluir  un  numero  de  archivos  diferentes. 

$archivos  =  array  ( ' primero . inc' ,  ' segundo . inc' ,  ' tercero . inc' ) ; 

for  ($i  =  0;  $i  <  count ( $archivos ) ;  $i++)  { 

include  $archivos [ $i ] ; 

} 


include ')  difiere  de  require  ')  en  que  la  sentencia  include  se  re-evalua  cada  vez  que  se  encuentra  (y  solo 
cuando  esta  siendo  ejecutada),  mientras  que  la  sentencia  require  ')  se  reemplaza  por  el  archivo 
referenciado  cuando  se  encuentra  por  primera  vez,  se  vaya  a  evaluar  el  contenido  del  archivo  o  no  (por 
ejemplo,  si  esta  dentro  de  una  sentencia  if  cuya  condition  evaluada  es  falsa). 

Debido  a  que  include')  es  una  construction  especial  del  lenguaje,  se  debe  encerrar  dentro  de  un  bloque 
de  sentencias  si  esta  dentro  de  un  bloque  condicional. 

/*  Esto  es  ERRONEO  y  no  funcionara  como  se  desea.  */ 

if  ($condicion) 

include ($archivo) ; 

else 

include ($otro) ; 

/*  Esto  es  CORRECTO.  */ 

if  ($condicion)  { 

include ($archivo) ; 

}  else  { 

include ($otro) ; 

} 


En  ambos,  PHP3  y  PHP4,  es  posible  ejecutar  una  sentencia  return  dentro  de  un  archivo  incluido  con 
include '),  para  terminar  el  procesado  de  ese  archivo  y  volver  al  archivo  de  comandos  que  lo  llamo. 
Existen  algunas  diferencias  en  el  modo  en  que  esto  funciona,  no  obstante.  La  primera  es  que  en  PHP3, 
return  no  puede  aparecer  dentro  de  un  bloque  a  menos  que  sea  un  bloque  de  funcion,  en  el  cual 
return  se  aplica  a  esa  funcion  y  no  al  archivo  completo.  En  PHP4,  no  obstante,  esta  restriction  no 
existe.  Tambien,  PHP4  permite  devolver  valores  desde  archivos  incluidos  con  include').  Se  puede 
capturar  el  valor  de  la  llamada  a  include')  como  se  harfa  con  una  funcion  normal.  Esto  genera  un  error  de 
interprete  en  PHP3. 
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Ejemplo  11-1.  include;)  en  PHP3  y  PHP4 

Asumamos  la  existencia  del  siguiente  archivo  (llamado  test .  inc)  en  el  mismo  directorio  que  el  archivo 
principal: 

<?php 

echo  "Antes  del  return  <br>\n"; 

if  (  1  )  { 

return  27; 

} 

echo  "Despues  del  return  <br>\n"; 

?> 

Asumamos  que  el  archivo  principal  (main .  html)  contiene  lo  siguiente: 

<?php 

$retval  =  include!  'test. inc'  ); 

echo  "El  archivo  devolvio:  ' $retval' <br>\n" ; 

?> 

Cuando  se  llama  a  main .  html  en  PHP3,  generara  un  error  del  interprete  en  la  linea  2;  no  se  puede 
capturar  el  valor  de  un  include')  en  PHP3.  En  PHP4,  no  obstante,  el  resultado  sera: 

Antes  del  return 
El  archivo  devolvio:  '27' 

Ahora,  asumamos  que  se  ha  modificado  main .  html  para  que  contenga  lo  siguiente: 

<?php 

include (  'test. inc'  ); 

echo  "De  vuelta  en  main . html<br>\n" ; 

?> 

En  PHP4,  la  salida  sera: 

Antes  del  return 
De  vuelta  en  main.html 

No  obstante,  PHP3  dara  la  siguiente  salida: 

Antes  del  return 

27De  vuelta  en  main.html 

Parse  error:  parse  error  in  /home/torben/public_html/phptest/main . html  on  line  5 

El  error  del  interprete  es  resultado  del  hecho  de  que  la  sentencia  return  esta  encerrada  en  un  bloque  de 
no-funcion  dentro  de  test .  inc.  Cuando  el  return  se  mueve  fuera  del  bloque,  la  salida  es: 

Antes  del  return 

27De  vuelta  en  main.html 

El  ’27’  espureo  se  debe  al  hecho  de  que  PHP3  no  soporta  devolver  valores  con  return  desde  archivos 
como  ese. 
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When  a  file  is  include  J)ed,  the  code  it  contains  inherits  the  variable  scope  of  the  line  on  which  the 
include')  occurs.  Any  variables  available  at  that  line  in  the  calling  file  will  be  available  within  the  called 
file.  If  the  include ')  occurs  inside  a  function  within  the  calling  file,  then  all  of  the  code  contained  in  the 
called  file  will  behave  as  though  it  had  been  defined  inside  that  function. 

If  the  include ')ed  file  is  called  via  HTTP  using  the  fopen  wrappers,  and  if  the  target  server  interprets  the 
target  file  as  PHP  code,  variables  may  be  passed  to  the  include  ')ed  file  using  an  URL  request  string  as 
used  with  HTTP  GET.  This  is  not  strictly  speaking  the  same  thing  as  include  jing  the  file  and  having  it 
inherit  the  parent  file’s  variable  scope;  the  script  is  actually  being  run  on  the  remote  server  and  the  result 
is  then  being  included  into  the  local  script. 

/*  This  example  assumes  that  someserver  is  configured  to  parse  ,php 

*  files  and  not  . txt  files.  Also,  'works'  here  means  that  the  variables 

*  $varone  and  $vartwo  are  available  within  the  include (Jed  file.  */ 

/*  Won't  work;  file.txt  wasn't  handled  by  someserver.  */ 
include  ( "http : / / someserver/ file . txt ?varone=l&vartwo=2 " ) ; 

/*  Won't  work;  looks  for  a  file  named  ' f ile . php?varone=l&vartwo=2 ' 

*  on  the  local  filesystem.  */ 
include  ( " f ile . php?varone=l&vartwo=2 " ) ; 

/ *  Works .  * / 

include  ( "http : / / someserver/ file . php?varone=l&vartwo=2 " ) ; 

$varone  =  1; 

$vartwo  =  2; 

include  ("file.txt");  /*  Works.  */ 
include  ( "file .php" ) ;  /*  Works.  */ 


See  also  require'),  require_once '),  include_once'),  readfile'j,  and  virtual'). 


require_once() 

The  require_onceO  statement  replaces  itself  with  the  specified  file,  much  like  the  C  preprocessor’s 
# include  works,  and  in  that  respect  is  similar  to  the  require ')  statement.  The  main  difference  is  that  in 
an  inclusion  chain,  the  use  of  require_onceO  will  assure  that  the  code  is  added  to  your  script  only  once, 
and  avoid  clashes  with  variable  values  or  function  names  that  can  happen. 

For  example,  if  you  create  the  following  2  include  files  utils  .  inc  and  foolib .  inc 

Ejemplo  11-2.  utils.inc 

<?php 

define (PHPVERSION,  floor (phpversion  ( ) ) ) ; 
echo  "GLOBALS  ARE  NICE\n"; 
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function  goodTeaO  { 

return  "Oolong  tea  tastes  good!"; 

} 

?> 


Ejemplo  11-3.  foolib.inc 

<?php 

require  ( "utils . inc" ) ; 
function  showVar ($var)  { 

if  (P HP VERS I ON  ==  4)  { 

print_r ($var) ; 

}  else  { 

dump_var ($var) ; 


} 

/ /  bunch  of  other  functions  .  .  . 
?> 


And  then  you  write  a  script  cause_error_require  .php 


Ejemplo  11-4.  cause_error_require.php 

<?php 

require ( " foolib . inc" ) ; 

/*  the  following  will  generate  an  error  */ 
require ( "utils . inc" ) ; 

$foo  =  array (" 1 ",  array (" complex" , "quaternion" )) ; 

echo  "this  is  requiring  utils. inc  again  which  is  also\n"; 

echo  "required  in  foolib . inc\n" ; 

echo  "Running  goodTea:  ". goodTea ()." \n" ; 

echo  "Printing  foo:  \n"; 

showVar ($foo) ; 

?> 

When  you  try  running  the  latter  one,  the  resulting  ouptut  will  be  (using  PHP  4.01pl2): 

GLOBALS  ARE  NICE 
GLOBALS  ARE  NICE 

Fatal  error:  Cannot  redeclare  causeerror()  in  utils. inc  on  line  5 


By  modifying  foolib.  inc  and  cause_errror_require  .php  to  use  require_onceO  instead  of 
require;)  and  renaming  the  last  one  to  avoid_error_require_once  .php,  we  have: 
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Ejemplo  11-5.  foolib.inc  (fixed) 


require_once ( "utils . inc" ) ; 
function  showVar ($var)  { 


Ejemplo  11-6.  avoid_error_require_once.php 

require_once ( "foolib . inc" ) ; 
require_once ( "utils . inc" ) ; 

$foo  =  array (" 1 ",  array (" complex" , "quaternion" )) ; 


And  when  running  the  latter,  the  output  will  be  (using  PHP  4.0.  Ipl2): 

GLOBALS  ARE  NICE 

this  is  requiring  globals.inc  again  which  is  also 
required  in  foolib.inc 

Running  goodTea:  Oolong  tea  tastes  good! 

Printing  foo: 

Array 

( 

[0]  =>  1 
[1]  =>  Array 
( 

[0]  =>  complex 
[1]  =>  quaternion 

) 


Also  note  that,  analogous  to  the  behavior  of  the  # include  of  the  C  preprocessor,  this  statement  acts  at 
"compile  time",  e.g.  when  the  script  is  parsed  and  before  it  is  executed,  and  should  not  be  used  for  parts 
of  the  script  that  need  to  be  inserted  dynamically  during  its  execution.  You  should  use  include_once))  or 
include ))  for  that  purpose. 

For  more  examples  on  using  require_once))  and  include_once  )),  look  at  the  PEAR  code  included  in  the 
latest  PHP  source  code  distributions. 

See  also:  require  '),  include  )),  include_once )),  get_required_files(),  get_included_files(),  readfile)),  and 
virtual)). 
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include_once() 

The  include_once ')  statement  includes  and  evaluates  the  specified  file  during  the  execution  of  the  script. 
This  is  a  behavior  similar  to  the  include;)  statement,  with  the  important  difference  that  if  the  code  from  a 
file  has  already  been  included,  it  will  not  be  included  again. 

As  mentioned  in  the  require_once'j  description,  the  includc_once ')  should  be  used  in  the  cases  in  which 
the  same  file  might  be  included  and  evaluated  more  than  once  during  a  particular  execution  of  a  script, 
and  you  want  to  be  sure  that  it  is  included  exactly  once  to  avoid  problems  with  function  redefinitions, 
variable  value  reassignments,  etc. 

For  more  examples  on  using  require_once;)  and  include_once '),  look  at  the  PEAR  code  included  in  the 
latest  PHP  source  code  distributions. 

See  also:  require  '),  include  ),  require_once;),  get_required_files(),  get_included_files(),  readfile'),  and 
virtual'). 
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Funciones  definidas  por  el  usuario 

Una  funcion  se  define  con  la  siguiente  sintaxis: 


function  foo  ($arg_l,  $arg_2,  $arg_n)  { 

echo  "Funcion  de  ejemplo.Xn"; 
return  $retval; 

} 


Cualquier  instruction  valida  de  PHP  puede  aparecer  en  el  cuerpo  de  la  funcion,  incluso  otras  funiones  y 
definiciones  de  clases 

En  PHP3,  las  funciones  deben  definirse  antes  de  que  se  referencien.  En  PHP4  no  existe  tal  requerimiento. 

PHP  no  soporta  la  sobrecarga  de  funciones,  y  tampoco  es  posible  redefinir  u  ocultar  funciones 
previamente  declaradas. 

PHP3  no  soporta  un  numero  variable  de  parametros,  aunque  si  soporta  parametros  por  defecto  (ver 
Valores  por  defecto  de  de  los  parametros  para  mas  information).  PHP4  soporta  ambos:  ver  Listas  de 
longitud  variable  de  parametros  y  las  referencias  de  las  funciones  func_num_args  j,  func_get_arg '),  y 
func_get_args()  para  mas  informacion. 


Parametros  de  las  funciones 


La  informacion  puede  suministrarse  a  las  funciones  mediante  la  lista  de  parametros,  una  lista  de 
variables  y/o  constantes  separadas  por  comas. 

PHP  soporta  pasar  parametros  por  valor  (el  comportamiento  por  defecto),  por  referencia,  y  parametros 
por  defecto  Listas  de  longitud  variable  de  parametros  solo  estan  soportadas  en  PHP4  y  posteriores;  ver 
Listas  de  longitud  variable  de  parametros  y  la  referencia  de  las  funciones  func_num_argsQ, 
func_get_arg '),  y  func_get_args ')  para  mas  informacion.  Un  efecto  similar  puede  conseguirse  en  PHP3 
pasando  un  array  de  parametros  a  la  funcion: 

function  takes_array ( $input )  { 

echo  "$input[0]  +  $ input [1]  =  ",  $input [ 0 ] +$input  [  1 ] ; 

} 


Pasar  parametros  por  referencia 

Por  defecto,  los  parametros  de  una  funcion  se  pasan  por  valor  (de  manera  que  si  cambias  el  valor  del 
argumento  dentro  de  la  funcion,  no  se  ve  modificado  fuera  de  ella).  Si  deseas  permitir  a  una  funcion 
modificar  sus  parametros,  debes  pasarlos  por  referencia. 
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Si  quieres  que  un  parametro  de  una  funcion  siempre  se  pase  por  referenda,  puedes  anteponer  un 
ampersand  (&)  al  nombre  del  parametro  en  la  definition  de  la  funcion: 

function  add_some_extra ( &$string)  { 

$string  .=  '  y  algo  mas . ' ; 

} 

$str  =  ' Esto  es  una  cadena,  '; 
add_some_extra ($str) ; 

echo  $str;  //  Saca  'Esto  es  una  cadena,  y  algo  mas.' 


Si  deseas  pasar  una  variable  por  referencia  a  una  funcion  que  no  toma  el  parametro  por  referencia  por 
defecto,  puedes  anteponer  un  ampersand  al  nombre  del  parametro  en  la  llamada  a  la  funcion: 

function  foo  ($bar)  { 

$bar  .  =  '  y  algo  mas . ' ; 

} 

$str  =  'Esto  es  una  cadena,  '; 
foo  ($str) ; 

echo  $str;  //  Saca  'Esto  es  una  cadena,  ' 
foo  (&$str) ; 

echo  $str;  //  Saca  'Esto  es  una  cadena,  y  algo  mas.' 


Parametros  por  defecto 

Una  funcion  puede  definir  valores  por  defecto  para  los  parametros  escalares  estilo  C++: 

function  makecoffee  ($type  =  "cappucino")  { 
return  "Hacer  una  taza  de  $type.\n"; 

} 

echo  makecoffee  (); 

echo  makecoffee  ("espresso"); 


La  salida  del  fragmento  anterior  es: 

Hacer  una  taza  de  cappucino. 
Hacer  una  taza  de  espresso. 


El  valor  por  defecto  tiene  que  ser  una  expresion  constante,  y  no  una  variable  o  miembro  de  una  clase. 
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En  PHP  4.0  tambien  es  posible  especificar  unset  como  parametro  por  defecto.  Esto  significa  que  el 
argumento  no  tomara  ningun  valor  en  absoluto  si  el  valor  no  es  suministrado. 

Destacar  que  cuando  se  usan  parametros  por  defecto,  estos  tienen  que  estar  a  la  derecha  de  cualquier 
parametro  sin  valor  por  defecto;  de  otra  manera  las  cosas  no  funcionaran  de  la  forma  esperada.  Considera 
el  siguiente  fragmento  de  codigo: 

function  makeyogurt  ($type  =  "acidophilus",  $flavour)  { 
return  "Haciendo  un  bol  de  $type  $f lavour . \n" ; 

} 

echo  makeyogurt  ("mora") ;  //  No  funcionara  de  la  manera  esperada 


La  salida  del  ejemplo  anterior  es: 

Warning:  Missing  argument  2  in  call  to  makeyogurt ( )  in 
/usr/local/etc/httpd/htdocs/php3test/functest . html  on  line  41 
Haciendo  un  bol  de  mora. 


Y  ahora,  comparalo  con: 

function  makeyogurt  ($flavour,  $type  =  "acidophilus")  { 
return  "Haciendo  un  bol  de  $type  $f lavour . \n" ; 

} 

echo  makeyogurt  ("mora");  //  funciona  como  se  esperaba 


La  salida  de  este  ejemplo  es: 

Haciendo  un  bol  de  acidophilus  mora. 


Lista  de  longitud  variable  de  parametros 

PHP4  soporta  las  listas  de  longitud  variable  de  parametros  en  las  funciones  definidas  por  el  usuario.  Es 
realmente  facil,  usando  las  funciones  func_num_argsO,  t'u  nc_get_arg y  fu  nc_get_args '). 

No  necesita  de  ninguna  sintaxis  especial,  y  las  listas  de  parametros  pueden  ser  escritas  en  la  llamada  a  la 
funcion  y  se  comportaran  de  la  manera  esperada. 
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Los  valores  se  retoman  usando  la  instruccion  opcional  return.  Puede  devolverse  cualquier  tipo  de  valor, 
incluyendo  listas  y  objetos. 


function  square  ($num)  { 
return  $num  *  $num; 

} 

echo  square  (4);  //  saca  '16'. 


No  puedes  devolver  multiples  valores  desde  una  funcion,  pero  un  efecto  similar  se  puede  conseguir 
devolviendo  una  lista. 


function  small_numbers ( )  { 

return  array  (0,  1,  2); 

} 


list  ($zero,  $one,  $two)  =  small_numbers ( ) ; 


old_f unction 

La  instruccion  old_function  permite  declarar  una  funcion  usando  una  sintaxis  identica  a  la  de 
PHP/FI2  (excepto  que  debes  reemplazar  ’function’  por  ’old_function’). 

Es  una  caracterfstica  obsoleta,  y  deberfa  ser  usada  linicamente  por  el  conversor  PHP/FI2->PHP3. 


Aviso 

Las  funciones  declaradas  como  oid_function  no  pueden  llamarse  desde  el 
codigo  interno  de  PHP.  Entre  otras  cosas,  esto  significa  que  no  puedes  usarlas  en 
funciones  como  usort)),  array_walk;),  y  register_shutdown_function;).  Puedes 
solventar  esta  limitacion  escribiendo  un  "wrapper"  (en  PHP3  normal)  que  a  su  vez 
llame  a  la  funcion  declarada  como  oid_function. 


Funciones  variable 


PHP  soporta  el  concepto  de  funciones  variable,  esto  significa  que  si  una  variable  tiene  unos  parentesis 
anadidos  al  final,  PHP  buscara  una  funcion  con  el  mismo  nombre  que  la  evaluacion  de  la  variable,  e 
intentara  ejecutarla.  Entre  otras  cosas,  esto  te  permite  implementar  retrollamadas  (callbacks),  tablas  de 
funciones  y  demas. 
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Ejemplo  12-1.  Ejemplo  de  funcion  variable 

<?php 

function  foo ( )  { 

echo  "Dentro  de  f oo ( ) <br>\n" ; 

} 

function  bar (  $arg  =  "  )  { 

echo  "Dentro  de  bar();  el  parametro  fue  ' $arg' . <br>\n" ; 

} 

$func  =  ' foo' ; 

$func  ( ) ; 

$func  =  ' bar' ; 

$func (  ' test'  ) ; 

?> 
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class 


Una  clase  es  una  coleccion  de  variables  y  de  funciones  que  acceden  a  esas  variables.  Una  clase  se  define 
con  la  siguiente  sintaxis: 

<?php 

class  Cart  { 

var  $items;  //  Items  en  nuestro  carro  de  la  compra 

//  Anadir  $num  articulos  de  tipo  $artnr  al  carro 

function  add_item  ($artnr,  $num)  { 

$this->items [ $artnr ]  +=  $num; 

} 

//  Sacar  $num  articulos  del  tipo  $artnr  del  carro 

function  remove_item  ($artnr,  $num)  { 
if  ( $this->items [ $artnr ]  >  $num)  { 

$this->items [$artnr]  -=  $num; 
return  true; 

}  else  { 

return  false; 


} 

} 

?> 


El  ejemplo  define  una  clase  llamada  Cart  que  consiste  en  un  array  asociativo  de  articulos  en  el  carro  y 
dos  funciones  para  meter  y  sacar  items  del  carro 

Las  clases  son  tipos,  es  decir,  son  plantillas  para  variables.  Tienes  que  crear  una  variable  del  tipo  deseado 
con  el  operador  new. 

$cart  =  new  Cart; 

$cart->add_item ( " 10 " ,  1); 


Este  ejemplo  crea  un  objeto  $cart  de  clase  Cart.  La  funcion  add_item()  de  ese  objeto  se  llama  para  anadir 
un  item  del  artfculo  numero  10  al  carro. 

Las  Clases  pueden  ser  extensiones  de  otras  clases.  Las  clases  extendidas  o  derivadas  tienen  todas  las 
variables  y  funciones  de  la  clase  base  y  lo  que  les  anadas  al  extender  la  definition.  La  herencia  multiple 
no  esta  soportada. 

class  Named_Cart  extends  Cart  { 
var  $owner; 

function  set_owner  ($name)  { 

$this->owner  =  $name; 
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} 


} 


Ese  ejemplo  define  una  clase  Named_Cart  (carro  con  nombre  o  dueno)  que  tiene  todas  las  variables  y 
funciones  de  Cart,  y  ademas  anade  la  variable  $owner  y  una  funcion  adicional  set_owner().  Un  carro  con 
nombre  se  crea  de  la  forma  habitual  y,  una  vez  hecho,  puedes  acceder  al  propietario  del  carro.  En  los 
carros  con  nombre  tambien  puedes  acceder  a  las  funciones  normales  del  carro: 

$ncart  =  new  Named_Cart;  //  Creamos  un  carro  con  nombre 
$ncart->set_owner  ("kris");  //  Nombramos  el  carro 

print  $ncart->owner ;  //  Imprimimos  el  nombre  del  propietario 

$ncart->add_item  ("10",  1);  //  Funcionalidad  heredada  de  Cart 


Entre  funciones  de  una  clase,  la  variable  $this  hace  referencia  al  propio  objeto.  Tienes  que  usar 
$this->loquesea  para  acceder  a  una  variable  o  funcion  llamada  loquesea  del  objeto  actual. 

Los  constructores  son  funciones  de  una  clase  que  se  llaman  automaticamente  al  crear  una  nueva  instancia 
(objeto)  de  una  clase.  Una  funcion  se  convierte  en  constructor  cuando  tiene  el  mismo  nombre  que  la 
clase. 

class  Auto_Cart  extends  Cart  { 
function  Auto_Cart  ()  { 

$this->add_item  ("10",  1) ; 

} 

} 


Este  ejemplo  define  una  clase  Auto_Cart  que  es  un  Cart  junto  con  un  constructor  que  inicializa  el  carro 
con  un  item  del  tipo  de  artfculo  "10"  cada  vez  que  se  crea  un  nuevo  Auto_Cart  con  "new".  Los 
constructores  tambien  pueden  recibir  parametros  y  estos  parametros  pueden  ser  opcionales,  lo  que  los 
hace  mas  utiles. 

class  Constructor_Cart  extends  Cart  { 

function  Constructor_Cart  ($item  =  "10",  $num  =  1)  { 

$this->add_item  ($item,  $num) ; 

} 

} 

//  Compramos  las  mismas  cosas  aburridas  de  siempre 
$def ault_cart  =  new  Constructor_Cart ; 

//  Compramos  las  cosas  interesantes 

$dif ferent_cart  =  new  Constructor_Cart  ("20",  17); 
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Atencion 

Para  las  clases  derivadas,  el  constructor  de  la  clase  padre  no  es  llamado 
automaticamente  cuando  se  llama  al  constructor  de  la  clase  derivada. 
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Captiulo  14.  References  Explained 


References  in  PHP  are  means  to  call  same  variable  content  with  different  names.  They  are  not  like  C 
pointers,  they  are  symbol  table  aliases.  Note  that  in  PHP,  variable  names  and  variable  content  are 
different,  so  same  content  can  have  different  names.  The  most  close  analogy  is  Unix  filenames  and  files  - 
variable  names  are  directory  entries,  while  variable  contents  is  the  file  itself.  References  can  be  thought 
of  as  hardlinking  in  Unix  filesystem. 


What  do  References 

PHP  references  allow  you  to  make  two  variables  to  refer  to  the  same  content.  Meaning,  when  you  do: 

$a  =&  $b 

it  means  that  $a  and  $b  point  to  the  same  variable. 

Nota:  $a  and  $b  are  completely  equal  here,  that's  not  $a  is  pointing  to  $b  or  vice  versa,  that’s  $a  and 
$b  pointing  to  the  same  place. 


The  second  thing  references  do  is  to  pass  variables  by-reference.  This  is  done  by  making  local  function 
variable  and  caller  variable  to  be  reference  to  the  same  content.  Example: 

function  foo  (&$var)  { 

$var++; 

} 

$a=5; 
foo  ( $  a ) ; 

will  make  $a  to  be  6.  This  happens  because  in  the  function  foo  the  variable  $var  refers  to  the  same 
content  as  $a. 

The  third  thing  reference  can  do  is  return  by-reference 

What  aren’t  References 


As  said  above,  references  aren’t  pointers.  That  means,  the  following  construct  won’t  do  what  you  expect: 


function 

$var 


foo  (&$var)  { 

=&  $GLOBALS [ "baz " ] ; 
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foo ( $bar ) ; 
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What  will  happen  that  $var  in  foo  will  be  bound  with  $bar  in  caller,  but  then  it  will  be  re -bound  with 
$GLOBALS  [  "baz "  ] .  There’s  no  way  to  bind  $bar  in  the  caller  to  something  else  using  reference 
mechanism,  since  $bar  is  not  available  in  the  function  foo  (it  is  represented  by  $var,  but  $var  has  only 
variable  contents  and  not  name-to- value  binding  in  the  calling  symbol  table). 


Returning  References 

Returning  by-refernce  it  is  useful  when  you  want  to  use  function  to  find  variable  which  should  be  bound 
to.  When  returning  references,  use  this  syntax: 

function  &find_var  ($param)  { 

.  . . code . . . 
return  $found_var; 

} 

$foo  =&  find_var  ($bar) ; 

$foo->x  =  2; 


In  this  example,  property  of  the  object  returned  by  the  find_var  function  would  be  set,  not  of  the  copy, 
as  it  would  be  without  using  reference  syntax. 

Nota:  Unlike  parameter  passing,  here  you  have  to  use  &  in  both  places  -  to  indicate  that  you  return 
by-reference,  not  a  copy  as  usual,  and  to  indicate  than  reference  binding  and  not  usual  assignment 
should  be  done  for  $foo. 


Unsetting  References 

When  you  unset  the  reference,  you  just  break  the  binding  between  variable  name  and  variable  content. 
This  does  not  mean  that  variable  content  will  be  destroyed.  For  example: 

$a  =  1; 

$b  =&  $a; 
unset  ( $  a ) ; 


won’t  unset  $b,  just  $a. 

Again,  it  might  be  useful  to  think  about  this  as  analogous  to  Unix  unlink  call. 
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Spotting  the  Reference 

Many  syntax  constructs  in  PHP  are  implemented  via  referencing  mechanisms,  so  everything  told  above 
about  reference  binding  also  apply  to  these  constructs.  Some  constructs,  like  passing  and  returning 
by-reference,  are  mentioned  above.  Other  constructs  that  use  references  are: 


global  References 

When  you  declare  variable  as  global  $var  you  are  in  fact  creating  reference  to  a  global  variable.  That 
means,  this  is  the  same  as: 

$var  =&  $GLOBALS [ "var " ] ; 


That  means,  for  example,  that  unsetting  $var  won’t  unset  global  variable. 


$this 


In  an  object  method,  $this  is  always  reference  to  the  caller  object. 
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Hay  4  tipos  de  errores  y  avisos  en  PHP.  Esto  son: 

•  1  -  Errores  Normales  de  Funciones  (Normal  Function  Errors) 

•  2  -  Avisos  Normales  (Normal  Warnings) 

•  4  -  Errores  del  Analizador  de  codigo  (Parser  Errors) 

•  8  -  Avisos  (Notices,  advertencia  que  puedes  ignorar,  pero  que  puede  implicar  un  error  en  tu  codigo. 


Los  4  numeros  de  arriba  son  sumados  para  definir  un  nivel  de  aviso  de  error.  El  nivel  de  aviso  de  error 
por  defecto  es  el  nivel  7,  el  cual  es  la  suma  de  1+2+4,  es  decir  todo  excepto  los  avisos.  Este  nivel  puede 
ser  cambiado  en  el  fichero  php3.ini  con  la  directiva  error_reporting.  Tambien  puede  ser  configurado  en  el 
fichero  de  configuration  del  servidor  de  paginas  Apache  httpd.conf,  con  la  directiva 
php3_error_reporting  o  tambien  se  puede  cambiar  en  tiempo  de  ejecucion  usando  la  funcion 
error_reporting  (). 

Todas  las  expresioness  PHP  pueden  tambien  ser  llamadas  con  el  prefijo  el  cual  desactiva  el  aviso  de 
errores  para  esa  expresion  en  particular.  Si  ocurre  un  error  en  una  expresion  en  tal  situation  y  la 
caracterfstica  track_errors  esta  habilitada,  podras  encontrar  el  mensaje  de  error  en  la  variable  global 
$php_errormsg. 
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PHP  no  esta  limitado  a  crear  solo  salidas  de  HTML.  Puede  ser  usado  tambien  para  crear  ficheros  de 
imagenes  GIF,  o  incluso  mejor  secuencias  de  imagenes  GIF.  Necesitara  compilar  PHP  con  la  libreria  de 
funciones  de  imagenes  GD  para  esta  tarea. 


Ejemplo  16-1.  Creadon  de  GIFs  con  PHP 

<?php 

Header ( "Content-type :  image/gif" ) ; 
$string=implode ($argv, "  "); 

$im  =  imagecreatef romgif ( " images/buttonl . gif " ) ; 
$orange  =  IraageColorAllocate ( $im,  220,  210,  60); 
$px  =  ( imagesx ( $im) -7 . 5*st rlen ( $string) ) /2 ; 
ImageString ($im, 3, $px, 9,  $string,  $orange)  ; 
ImageGif ($im)  ; 

ImageDestroy ($im)  ; 

?> 


Este  ejemplo  sera  llamado  desde  una  pagina  con  una  lfnea  como  esta:  <imgsrc="button.php3?text">  Este 
script  de  arriba  button.php3  toma  esta  cadena  "text"  la  situa  sobre  la  imagen  base,  en  este  caso  es 
"images/buttonl. gif"  y  muestra  la  imagen  resultante.  Esta  es  una  forma  muy  conveniente  para  evitar 
tener  que  dibujar  un  nuevo  boton  cada  vez  que  quiera  cambiar  el  texto  del  mismo.  Con  este  metodo  los 
botones  son  generados  dinamicamente. 
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Las  caracterfticas  de  autentificacion  HTTP  en  PHP  solo  estan  disponibles  cuando  se  esta  ejecutando 
como  un  modulo  en  Apache  y  hasta  ahora  no  lo  estan  en  la  version  CGI.  En  un  script  PHP  como  modulo 
de  Apache,  se  puede  usar  la  funcion  header  )  para  enviar  un  mensaje  de  "Autentificacion  requerida"  al 
navegador  cliente  haciendo  que  muestre  una  ventana  de  entrada  emergente  con  nombre  de  usuario  y 
contrasena.  Una  vez  que  el  usuario  ha  rellenado  el  nombre  y  la  contrasena,  la  URL  que  contiene  el  script 
PHP  vuelve  a  ser  llamada  con  las  variables  $PHP_AUTH_USER,  $PHP_AUTH_PW  y 
$PHP_AUTH_TYPE  rellenas  con  el  nombre  de  usuario,  la  contrasena  y  el  tipo  de  autentificacion 
respectivamente.  Solo  autentificacion  "Basica"  esta  soportada  en  este  momento.  Consulte  la  funcion 
header  ')  para  mas  information. 

Un  fragmento  de  script  de  ejmplo  que  fuerce  la  autentificacion  del  cliente  en  una  pagina  serfa  como  el 
siguiente: 

Ejemplo  17-1.  Ejemplo  de  autentificacion  HTTP 

<?php 

if  (  ! isset ( $PHP_AUTH_USER)  )  { 

Header ( "WWW-Autentificacion :  Basic  realm=\"Mi  ReinoV'"); 

Header ( "HTTP/1 . 0  401  No  autorizado" )  ; 

echo  "Texto  a  enviar  si  pulsa  el  boton  Cancelar\n" ; 

exit; 

}  else  { 

echo  "Hola  $PHP_AUTH_USER . <P>" ; 

echo  "Ha  introducido  $PHP_AUTH_PW  como  su  contrasena . <P>" ; 

} 

?> 


En  vez  de,  sencillamente,  mostrar  $PHP_AUTH_USER  y  $PHP_AUTH_PW,  seguramente  quiera 
comprobar  la  validez  del  nombre  de  usuario  y  la  contrasena.  Tal  vez  enviando  una  consulta  a  una  base  de 
datos  o  buscando  el  usuario  en  un  fichero  dbm. 

Vigile  aquf  los  navegadores  Interner  Explorer  con  bugs.  Parecen  muy  quisquillosos  con  el  orden  de  las 
cabeceras.  Enviar  la  cabecera  WWW-Autentificacion  antes  que  la  cabecera  HTTP/1 .0  401  parece  ser  el 
truco  por  ahora. 

Para  prevenir  que  alguien  escriba  un  script  que  revele  la  contrasena  de  una  pagina  que  ha  sido 
autentificada  a  traves  de  algun  mecanismo  externo  tradicional,  las  variables  PHP_AUTH  no  seran 
rellenadas  si  algun  tipo  de  autentificacion  externo  ha  sido  activado  para  una  pagina  en  particular.  En  este 
caso,  la  variable  $REMOTE_USER  puede  ser  usada  para  identificar  al  usuario  autentificado 
externamente. 

Nota,  a  pesar  de  todo,  lo  ya  dicho  no  proteje  de  que  alguien  que  controle  una  URL  no  autentificada  robe 
contrasenas  de  URLs  autentificadas  en  el  mismo  servidor. 

Tanto  Netscape  como  Internet  Explorer  borraran  la  cache  de  la  ventana  de  autentificacion  en  el 
navegador  local  despues  de  recibir  una  respuesta  401  del  servidor.  Esto  puede  usarse,  de  forma  efectiva, 
para  "desconectar"  a  un  usuario,  forzandole  a  reintroducir  su  nombre  y  contrasena.  Algunas  personas 
usan  esto  para  "hacer  caducar"  entradas,  o  para  proveer  un  boton  de  "desconectar". 
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Ejemplo  17-2.  Ejemplo  de  autentificacion  HTTP  forzando  una  reentrada 

<?php 

function  authenticate  ( )  { 

Header (  "WWW-Authenticate :  Basic  realm=\"Test  Autentificacion  SistemaV'"); 

Header (  "HTTP/1.0  401  No  autorizado" ) ; 

echo  "Debe  introducir  un  nombre  de  usuario  y  contrasena  validos  para  acceder  a 
este  recurso\n"; 
exit  ; 

} 

if ( ! isset ( $PHP_AUTH_USER)  ||  ($SeenBefore  ==  1  &&  ! strcmp ( $01dAuth,  $PHP_AUTH_USER) )  )  { 

authenticate  ( ) ; 

} 

else  { 

echo  "Bienvenido:  $PHP_AUTH_USER<BR>" ; 
echo  "Old:  $01dAuth"; 

echo  " <FORM  ACTION=\ " $PHP _ SELF \ "  METHOD=POST>\n" ; 

echo  " <INPUT  TYPE=HIDDEN  NAME=\ " SeenBef ore\ "  VALUE=\ " 1\ " >\n" ; 

echo  " <INPUT  TYPE=HIDDEN  NAME=\ "01dAuth\ "  VALUE=\ " $PHP_AUTH_USER\ ">\n" ; 

echo  " <INPUT  TYPE=Submit  VALUE=\"Re  AuthenticateX ">\n" ; 

echo  "</FORM>\n"; 

} 


Este  comportamiento  no  es  requerido  por  el  estandar  de  autentificacion  basica  de  HTTP,  por  lo  que 
nunca  debe  depender  de  esto.  Pruebas  con  Lynx  han  demostrado  que  Lynx  no  borra  las  credenciales  de 
autentificacion  con  una  respuesta  401  del  servidor,  por  lo  que  pulsando  atras  y  despues  adelante  abrirfa  el 
recurso  de  nuevo  (siempre  que  los  requerimientos  de  contrasena  no  hayan  cambiado). 

Ademas  note  que  esto  no  funciona  usando  el  servidor  IIS  de  Microsoft  y  la  version  CGI  de  PHP  debido  a 
una  limitacion  del  IIS 


118 


Capi'tulo  18.  Cookies 


119 


Capitulo  18.  Cookies 


PHP  soporta  transparentemente  cookies  HTTP  Las  Cookies  son  un  mecanismo  que  sirve  para  almacenar 
datos  en  el  navegador  del  usuario  remoto,  para  asi  poder  identificar  al  usuario  cuando  vuelva.  Se  pueden 
poner  cookies  usando  la  funcion  setcookies().  Las  Cookies  son  parte  de  la  cabecera  HTTP,  por  tanto  la 
funcion  setcookie ')  debe  ser  llamada  antes  de  que  se  produzca  cualquier  salida  al  navegador.  Esta 
limitacion  es  la  misma  a  la  de  la  funcion  header^). 

Cualquier  cookie  enviada  a  ti  desde  el  cliente,  automaticamente  se  convertira  en  una  variable  PHP  igual 
como  ocurre  con  los  metodos  de  datos  GET  y  POST.  Si  deseas  asignar  multiples  valores  a  una  cookie 
simple,  anade  simplemente  []  a  el  nombre  de  la  cookie.  Para  mas  detalles  ver  la  funcion  setcookie  '). 
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Capitulo  19.  El  envi'o  de  archivos 


PHP  es  capaz  de  recibir  envfos  de  archivo  de  cualquier  navegador  que  cumpla  la  norma  RFC- 1867  (entre 
los  que  se  incluyen  Netscape  Navigator  3  o  posterior,  Microsoft  Internet  Explorer  3  con  un  parche  o 
posterior  sin  este).  Esta  caracterfstica  permite  que  los  usuarios  envien  archivos  de  texto  y  binarios. 

Mediante  la  autentificacion  y  funciones  de  manejo  de  archivos  de  PHP,  es  posible  un  control  total  de 
quien  puede  enviar  archivos  y  que  se  hace  con  estos  una  vez  recibidos. 

Es  importante  destacar  que  PHP  tambien  soporta  el  metodo  PUT  para  envfo  de  archivos  tal  y  como  lo 
utiliza  Netscape  Composer  y  el  cliente  Amaya  de  W3C.  Consulte  Soporte  del  metodo  PUT  para  mas 
detalles. 

Una  pagina  de  envfo  de  archivos  se  puede  crear  mediante  un  formulario  parecido  a  este: 

Ejemplo  19-1.  Formulario  de  envio  de  archivo 

&lt;FORM  ENCTYPE=&quot;multipart/form-data&quot;  ACTION=&quot ; _URL_&quot ;  METHOD=POST&gt; 
&lt ; INPUT  TYPE=&quot ; hidden&quot ;  name=&quot ; MAX_FILE_SIZE&quot ;  value=&quot ; lOOO&quot ; &gt ; 
Enviar  este  archivo:  &lt; INPUT  NAME=&quot; userfile&quot;  TYPE=&quot; f ile&quot; &gt; 

&lt ; INPUT  TYPE=&quot ; submit Squot ;  VALUE=&quot ; Enviar&quot ; &gt ; 

&lt; /FORM&gt ; 


La  _URL_  debe  tener  como  destino  un  script  PHP  El  campo  MAX_FILE_SIZE  debe  encontrarse  antes 
del  campo  INPUT  y  su  valor  determina  el  tamano  maximo  de  archivo  que  se  puede  enviar  en  bytes.  Tras 
la  recepcion  del  archivo  se  definiran  en  el  script  PHP  destino  las  siguientes  variables: 


•  $userfile  -  El  archivo  temporal  que  se  ha  guardado  en  el  servidor. 

•  $userfile_name  -  El  nombre  original  del  archivo  enviado. 

•  $userfile_size  -  El  tamano  del  archivo  recibido. 

•  $userfile_type  -  El  tipo  mime  del  archivo  si  el  navigador  envio  esta  informacion.  Por  ejemplo: 
&quot;image/gif&quot; . 

Es  importante  recordar  que  la  primera  palabra  &quot;$userfile&quot;  de  estas  variables  corresponde  al 
nombre  ("NAME=")  del  campo  "INPUT  TYPE=file"  del  formulario.  En  el  ejemplo  anterior  usamos 
&quot;userfile&quot;. 

Los  archivos  enviados  seran  guardados  en  el  directorio  temporal  por  defecto  del  servidor.  Podemos  variar 
este  directorio  mediante  la  variable  de  entorno  TMPDIR  en  el  entorno  donde  corre  PHP.  No  se  puede 
establecer  este  valor  usando  putenv ')  desde  un  script  PHP. 

El  script  PHP  que  recibe  el  archivo  enviado  debe  implementar  las  acciones  que  se  deben  llevar  a  cabo 
con  el  archivo  acabado  de  recibir.  Por  ejemplo  se  podria  utilizar  $file_size  para  decidir  descartar  los 
archivos  que  sean  demadiado  pequenos  o  demasiado  grandes.  Sean  cual  sean  las  acciones  a  tomar  se 
debe  borrar  el  archivo  temporal  o  moverlo  a  algun  otro  directorio. 

El  archivo  recibido  sera  eliminado  inmediatamente  del  directorio  temporal  al  finalizar  el  script  PHP  que 
lo  recibio  si  no  ha  sido  movido  o  renombrado. 
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El  valor  de  MAX_FILE_SIZE  no  puede  ser  mayor  que  el  tamano  del  archivo  que  se  especifica  en  la 
variable  upload_max_filesize  del  archivo  PHP3.ini  o  la  correspondiente  directiva 
php3_upload_max_filesize  de  Apache.  Por  defecto  es  2  Megabytes. 

El  servidor  CERN  parece  que  elimina  cualquier  cosa  antes  del  primer  espacio  en  bianco  en  la  cabecera 
mime  content-type  que  recibe  de  los  clientes.  Mientras  esto  no  varie,  CERN  httpd  no  podra  soportar  el 
envio  de  archivos. 


Envio  de  mas  de  un  archivo 


Es  posible  el  envio  de  varios  archivos  simultaneamente  y  poder  clasihcar  la  information 
automaticamente  por  arrays.  Esto  de  hace  de  la  misma  manera  en  que  se  organizan  por  arrays  los 
SELECT  o  CHECKBOX: 

Nota:  El  soporte  para  multiple  envios  de  archivos  se  anadio  en  la  version  3.0.10 


Ejemplo  19-2.  Formulario  de  envio  multiple  de  archivos 

&lt;form  action=&quot ; file-upload . html&quot ;  method=&quot ; post&quot ;  enctype=&quot ; multipart 
data&quot; &gt; 

Enviar  estos  archivos : &lt ; br&gt ; 

&lt ; input  name=&quot ;userfile[] &quot ;  type=&quot ; f ile&quot ; &gt ; & It ; br&gt ; 

Sit ; input  name=&quot ; user file [] &quot ;  type=&quot ; f ile&quot ; &gt ;& It ; br&gt ; 

&lt ; input  type=&quot ; submit Squot ;  value=&quot ; Enviar&quot ; &gt ; 

&lt ; / f orm&gt ; 


Cuando  el  formulario  es  procesado,  los  arrays  $userfile,  $userf  ile_name,  y  $userfile_size  se 
crearan  de  alcance  global  (igual  que  $HTTP_POST_VARS).  Cada  uno  sera  un  array  con  indice  numerico 
con  los  valores  apropiados  para  los  archivos  enviados. 

Por  ejemplo,  supongamos  que  los  siguientes  archivos  /home/test/review. html  y 
/home/test/xwp . out  son  enviados.  En  este  caso,  $userfile_name  [0]  almacenaria  el  valor 
review .  html,  y  $userf  ile_name  [  1  ]  almacenaria  el  valor  xwp .  out.  Asi,  $userf  ile_size  [  0  ] 
almacenaria  el  tamano  de  review .  html  y  asi  con  los  valores  siguientes. 
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Soporte  del  metodo  PUT 

PHP  soporta  el  metodo  HTTP  PUT  que  usan  aplicaciones  como  Netscape  Composer  y  Amaya  de  W3C. 
Las  peticiones  PUT  son  mas  sencillas  que  el  metodo  POST  Un  ejemplo: 

PUT  /path/f ilename . html  HTTP/1.1 


Esto  normalmente  significaria  que  el  cliente  remoto  quiere  salvar  el  contenido  como:  /path/filename. html 
en  tu  arbol  web.  Logicamente  no  una  buena  idea  que  la  gente  pueda  escribir  en  tu  arbol  web.  Para 
manipular  esta  peticion  debes  decirle  al  servidor  que  esta  peticion  sea  atendida  por  un  script  PHP.  En 
Apache,  por  ejemplo,  se  utiliza  para  esto  la  directiva  Script  en  los  alguno  de  los  archivos  de 
configuracion  del  servidor.  Un  sitio  tfpico  de  uso  es  dentro  del  bloque  &lt;Directory&gt;  o  quizas  en  el 
bloque  &lt;Virtualhost&gt;.  Una  linia  asf  deberia  hacer  esta  funcion: 

Script  PUT  /put.php3 


Esto  le  dice  a  Apache  que  envie  todas  peticiones  PUT  para  URIs  que  contengan  esta  linia  al  script 
put.php3.  Se  asume  que  PHP  se  encuentra  activo  y  con  la  extension  php3  enlazada  a  el. 

Dentro  del  script  put.php3  se  podrfa  implementar  algo  asi: 

&lt; ?  copy ( $PHP_UPLOADED_FILE_NAME ,  $DOCUMENT_ROOT . $REQUEST_URI )  ;  ?&gt; 


Esto  copiaria  el  archivo  a  la  localization  requerida  por  el  cliente  remoto.  Aqui  se  pueden  ejecutar 
funciones  de  autentificacion  de  usuario  o  cualquier  otro  tipo  de  chequeo.  El  archivo  se  guarda  en  el 
archivo  temporal  del  sistema  servidor  de  la  misma  manera  que  el  Metodo  POST  Cuando  la  peticion 
finaliza,  el  archivo  temporal  es  eliminado.  En  consequencia  el  script  dede  proceder  al  trato  de  este 
inmediatamente,  ya  sea  para  copiarlo,  renombrarlo,  etc.  El  archivo  se  encuentra  en  la  variable 
$PHP_PUT_FILENAME,  y  el  destino  sugerido  por  el  cliente  en  la  variable  $REQUEST_URI  (puede 
variar  en  servidores  diferentes  de  Apache).  No  es  necesario  hacer  caso  al  destino  sugerido  por  el  cliente. 
Por  ejemplo  se  podrfan  copiar  los  archivos  enviados  a  directorios  especialmente  designados  para  esta 
tarea. 
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Siempre  que  el  soporte  para  la  "envoltura  URL  fopen"  este  habilitado  cuando  se  configura  PHP  (lo  cual 
ocurre  a  menos  que  se  pasa  explfcitamente  la  opcion  — disable-url-fopen-wrapper  a  configure), 
se  pueden  usar  URLs  HTTP  y  FTP  con  la  mayorfa  de  las  funciones  que  toman  un  archivo  como 
parametro,  incluyendo  las  sentencias  require')  e  include'). 

Nota:  No  se  pueden  usar  archivos  remotos  en  las  sentencias  include [)  y  require;)  en  Windows. 


Por  ejemplo,  se  puede  usar  este  para  abrir  un  archivo  en  un  servidor  web  remoto,  analizar  en  la  salida  la 
informacion  que  se  quiera,  y  entonces,  usar  la  informacion  en  una  consulta  a  base  de  datos,  o 
simplemente  para  sacarls  en  un  estilo  que  coincida  con  el  resto  de  su  sitio  web. 


Ejemplo  20-1.  Obtener  el  titulo  de  una  pagina  remota 

<?php 

$archivo  =  f open  (  "http :/ /www . php . net /"  ,  "r"); 

if  (  !  $archivo)  { 

echo  "<p>No  se  pudo  abrir  el  archivo  remoto. \n"; 
exit; 

} 

while  ( ! feof ($archivo) )  { 

$linea  =  fgets ( $archivo,  1024); 

/*  Esto  solo  funciona  si  el  titulo  y  sus  etiquetas 
estan  en  una  linea.  */ 

if  (eregi ( "<title> ( . * ) </title>" ,  $linea,  $salida) )  { 

$title  =  $salida[l]; 
break; 

} 

} 

fclose ( $f ile) ; 


Tambien  se  puede  escribir  a  archivos  en  un  FTP  siempre  que  se  conecte  como  un  usuario  con  los 
correctos  derechos  de  acceso,  y  el  archivo  no  exista  ya.Para  conectar  como  un  usuario  distinto  de 
’anonymous’,  se  necesita  especificar  el  nombre  de  usuario  (y  posiblemente  contrasena)  dentro  de  la 
URL,  tales  como  ’ftp://usuario:clave@ftp.ejemplo.com/camino/a/archivo’.  (Se  puede  usar  la  misma 
clase  de  sintaxis  para  acceder  a  archivos  via  HTTP  cuando  se  requerfa  una  autenticacio  de  same  sort  of 
syntax  to  access  files  via  HTTP  when  they  require  Basic  authentication.) 


Ejemplo  20-2.  Storing  data  on  a  remote  server 

<?php 

$file  =  fopen (" ftp : //ftp . php . net/incoming/outputf ile"  ,  "w"); 

if  ( ! $f ile)  { 

echo  "<p>Unable  to  open  remote  file  for  writing. \n"; 
exit; 
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} 

/*  Write  the  data  here.  */ 
f put s  ($file,  " $HTTP_USER_AGENT\n" )  ; 
fclose ( $f ile) ; 


Nota:  You  might  get  the  idea  from  the  example  above  to  use  this  technique  to  write  to  a  remote  log, 
but  as  mentioned  above,  you  can  only  write  to  a  new  file  using  the  URL  fopen()  wrappers.  To  do 
distributed  logging  like  that,  you  should  take  a  look  at  syslogl). 
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Nota:  Todo  lo  siguiente  se  aplica  a  partir  de  la  3.0.7  y  posterior. 


Internamente  en  PHP  se  mantiene  el  estado  de  la  conexion.  Hay  3  posibles  estados: 


•  0- NORMAL 

•  1  -  ABORTED  (Aboitado) 

•  2  -  TIMEOUT  (Fuera  de  tiempo) 


Cuando  un  script  PHP  se  esta  ejecutando  se  activa  el  estado  NORMAL.  Si  el  cliente  remoto  se 
desconecta,  se  pasa  al  estado  ABORTADO.  Esto  suele  ocurrir  cuando  el  usuario  pulsa  en  el  boton  STOP 
del  navegador.  Si  se  alcanza  el  lfmite  de  tiempo  impuesto  por  PHP  (ver  set_time_limit()),  se  pasa  al 
estado  TIMEOUT. 

Puedes  decidir  si  quieres  que  la  desconexion  de  un  cliente  cause  que  tu  script  sea  abortado.  Algunas 
veces  es  comodo  que  tus  scripts  se  ejecuten  por  completo,  incluso  si  no  existe  ya  un  navegador  remoto 
que  reciba  la  salida.  El  comportamiento  por  defecto  es  sin  embargo,  que  tu  script  se  aborte  cuando  el 
cliente  remoto  se  desconecta.  Este  comportamiento  puede  ser  configurado  via  la  directiva 
ignore_user_abort  en  el  fichero  php3.ini,  o  tambien  con  la  funcion  ignore_user_abort ').  Si  no  le 
espeficicas  al  PHP  que  cuando  un  usuario  aborte  lo  ignore,  tu  script  terminara  su  ejecucion.  La  unica 
exception  es  si  tienes  registrada  un  funcion  de  desconexion  usando  la  funcion 

register_shutdown_function ').  Con  una  funcion  de  desconexion,  cuando  un  usuario  remoto  pulsa  en  el 
boton  STOP,  la  proxima  vez  que  tu  script  intenta  mostrar  algo,  PHP  detecta  que  la  conexion  ha  sido 
abortada  y  se  llama  a  la  funcion  de  desconexion.  Esta  funcion  de  desconexion  tambien  se  llama  al  final 
de  la  ejecucion  de  tu  script  cuando  se  ha  ejecutado  normalmente,  de  manera  que  si  quieres  hacer  algo 
diferente  en  caso  de  que  un  cliente  se  haya  desconectado,  puedes  usar  la  funcion  connection_abortcd  ). 
Esta  funcion  devuelve  verdadero  si  la  conexion  fue  abortada. 

Tu  script  tambien  se  puede  terminar  por  un  temporizador  interno.  El  timeout  por  defecto  es  de  30 
segundos.  Se  puede  cambiar  usando  la  directiva  max_execution_time  en  el  fichero  php3.ini  o  la 
correspondiente  directiva  php3_max_execution_time  en  la  configuration  del  servidor  de  paginas 
Apache,  como  tambien  con  la  funcion  set_time_limit').  Cuando  el  temporizador  expira,  el  script  se 
aborta  como  en  el  caso  de  la  desconexion  del  cliente,  de  manera  que  si  se  ha  definido  una  funcion  de 
desconexion,  esta  se  llamara.  Dentro  de  esta  funcion  de  desconexion,  puedes  comprobar  si  fue  el  timeout 
el  que  causo  que  se  llamara  a  la  funcion  de  desconexion,  llamando  a  la  funcion  connection_timeout'). 
Esta  funcion  devolvera  verdadero  si  el  timeout  causa  que  se  llame  a  la  funcion  de  desconexion. 

Hay  que  destacar  que  ambos,  el  estado  ABORTED  y  el  TIMEOUT,  se  pueden  activar  al  mismo  tiempo. 
Esto  es  posible  si  le  dices  a  PHP  que  ignore  las  desconexiones  intencionadas  de  los  usuarios.  PHP  aun 
notara  el  hecho  de  que  el  usuario  puede  haberse  desconectado,  pero  el  script  continuara  ejecutandose.  Si 
se  alcanza  el  tiempo  llmite  de  ejecucion  sera  abortado  y,  si  se  ha  definido  una  funcion  de  desconexion, 
esta  sera  llamada.  En  este  punto,  encontraras  que  las  funciones  connection_timeout ')  y 
connection_aborted  )  devuelven  verdadero.  Puedes  comprobar  ambos  estados  de  una  manera  simple 
usando  la  funcion  connection_status().  Esta  funcion  devuelve  un  campo  de  bit  de  los  estados  activos. 
De  este  modo,  si  ambos  estados  estan  activos  devolverla  por  ejemplo  un  valor  3. 
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Las  conexiones  persistentes  son  enlaces  SQL  que  no  se  cierran  cuando  termina  la  ejecucion  del  archivo 
de  comandos.  Cuando  se  pide  una  conexion  persistente,  PHP  comprueba  si  hay  ya  una  conexion 
persistente  identica  (que  permanecla  abierta  desde  antes)  -  y  si  existe,  la  usa.  Si  no  existe,  crea  un  enlace. 
Una  conexion  ’identica’  es  una  conexion  que  se  abrio  hacia  el  mismo  "host",  con  el  mismo  nombre  de 
usuario  y  la  misma  contrasena  (donde  sea  aplicable). 

La  gente  que  no  esta  familiarizada  con  el  modo  como  trabajan  y  distribuyen  la  carga  los  servidores 
"web"  puede  confundir  que  persistente  significa  lo  que  no  es.  En  particular,  ellas  no  te  dan  la  habilidad 
de  abrir  ’sesiones  de  usuario’  en  el  mismo  enlace  SQL,  no  dan  la  habilidad  de  construir  una  transaction 
de  forma  eficiente,  y  no  hacen  un  monton  de  otras  cosas.  De  hecho,  para  ser  extremadamente  claros 
sobre  el  tema  las  conexiones  persistentes  no  te  dan  ninguna  functionalidad  que  no  fuera  posible  con  sus 
hermanas  no-persistentes. 

6Por que? 

Esto  tiene  que  ver  con  el  modo  como  funcionan  los  servidores  "web".  Hay  tres  modos  en  que  un  servidor 
"web"  puede  utilizar  PHP  para  generar  paginas  web. 

El  primer  metodo  es  usar  PHP  como  una  capa  CGI.  Cuando  corre  de  este  modo,  se  crea  y  destruye  una 
instancia  del  interprete  PHP  por  cada  pagina  solicitada  (para  una  pagina  PHP)  a  tu  servidor.  Debido  a 
que  se  destruye  despues  de  cada  peticion,  cualquier  recurso  que  adquiera  (como  un  enlace  a  un  servidor 
de  base  de  datos  SQL)  se  cierra  cuando  es  destruido.  En  este  caso,  no  se  gana  nada  si  se  intentan  usar 
conexiones  persistentes. 

El  segundo,  y  mas  popular,  metodo  es  correr  PHP  como  un  modulo  en  un  servidor  web  multiproceso,  lo 
cual  actualmente  solo  incluye  Apache.  Un  servidor  multiproceso  tiene  tlpicamente  un  proceso  (el  padre) 
que  coordina  un  conjunto  de  procesos  (sus  hijos)  que  realmente  hacen  el  trabajo  se  servir  las  paginas 
web.  Cuando  entra  cada  peticion  de  un  cliente,  es  entregada  a  uno  de  los  hijos  que  no  este  ya  sirviendo  a 
otro  cliente.  Esto  significa  que  cuando  el  mismo  cliente  hace  una  segunda  petcion  al  servidor,  puede  ser 
atendidp  por  un  proceso  hijo  distinto  del  de  la  primera  vez.  Lo  que  una  conexion  persistente  hace  por  ti 
en  este  caso  es  hacerlo  de  tal  modo  que  cada  proceso  hijo  solo  necesita  conectar  a  tu  SQL  server  la 
primera  vez  que  sirve  una  pagina  que  hace  uso  de  una  conexion  asf.  Cuando  otra  pagina  solicita  una 
conexion  a  SQL  server,  puede  reutilizar  la  conexion  que  el  hijo  establecio  previamente. 

El  ultimo  metodo  es  usar  PHP  como  un  "plug-in"  para  un  servidor  web  multihilo.  En  la  actualidad  es 
solamente  teorico  —  PHP  no  funciona  aun  como  "plug-in"  para  ningun  servidor  web  multihilo.  Hay 
trabajo  en  progreso  para  soportar  ISAPI,  WSAPI  y  NSAPI  (en  Windows),  lo  cual  permitira  a  PHP  ser 
utilizado  como  "plug-in"  para  servidores  web  multihilo  como  Netscape  FastTrack,  Internet  Information 
Server  (IIS)  de  Microsoft,  y  O’Reilly’s  WebSite  Pro.  Cuando  esto  ocurra,  el  comportamiento  sera 
exactamente  el  mismo  que  para  el  modelo  de  multiprocesador  descrito  anteriormente. 

Si  las  conexiones  persistentes  no  aportan  ninguna  funcionalidad  anadida,  (jpara  que  son  buenas? 

La  respuesta  aqui  es  extremadamente  simple  —  eficiencia.  Las  conexiones  persistentes  son  buenas  si  las 
cabeceras  de  control  para  crear  un  enlace  a  tu  servidor  SQL  es  alta.  Que  estas  cabeceras  sean  o  no 
realmente  altas  depende  de  muchos  factores.  Como,  que  clase  de  base  de  datos  es,  si  esta  o  no  situada  en 
el  mismo  ordenador  que  el  servidor  web,  como  esta  de  cargada  la  maquina  donde  se  encuentre  el 
servidor  SQL,  y  otras  asl.  El  hecho  fundamental  es  que  si  la  cabecera  de  conexion  es  alta,  las  conexiones 
persistentes  te  ayudan  considerablemente  .  Ellas  hacen  que  el  proceso  hijo  simplemente  conecte 
solamente  una  vez  durante  todo  su  intervalo  de  vida,  en  vez  de  cada  vez  que  procesa  una  pagina  que 
requiere  conectar  al  servidor  SQL.  Esto  significa  que  por  cada  hijo  que  abrio  una  conexion  persistente 
tendra  su  propia  conexion  persistente  al  servidor.  Por  ejemplo,  si  tienes  20  procesos  hijos  distintos  que 


131 


Capitulo  22.  Conexiones  persistentes  a  bases  de  datos 


corran  un  archivo  de  comandos  que  cree  una  conexion  persistente  a  tu  servidor  SQL,  tendrfas  20 
conexiones  diferentes  a  ti  servidor  SQL,  una  por  cada  hijo. 

Un  resumen  importante.  Las  conexiones  persistentes  fueron  disenadas  para  tener  una  equivalencia 
uno-a-uno  con  las  conexiones  normales.  Eso  significa  que  deberfs  siempre  ser  capaz  de  reemplazar  las 
conexiones  persistentes  por  conexiones  no  persistentes  y  no  cambiara,  el  modo  como  se  comporta  el 
archivo  de  comandos.  Puede  cambiar  la  eficiencia  del  archivo  de  comandos  (y  probablemete  lo  hara), 
jpero  no  su  comportamiento! 
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Capitulo  23.  Safe  Mode 


Safe  Mode  is  an  attempt  to  solve  the  shared-server  security  problem.  It  is  architecturally  incorrect  to  try 
to  solve  this  problem  at  the  PHP  level,  but  since  the  alternatives  at  the  web  server  and  OS  levels  aren’t 
very  realistic,  many  people,  especially  ISP’s,  use  Safe  Mode  for  now. 

The  configuration  directives  that  control  Safe  Mode  are: 

safe_mode  =  Off 

open_basedir  = 

safe_mode_exec_dir  = 

safe_mode_allowed_env_vars  =  PHP_ 

safe  mode  protected  env  vars  =  LD_LIBRARY_PATH 

disable_functions  = 


When  safe_mode  is  on,  PHP  checks  to  see  if  the  owner  of  the  current  script  matches  the  owner  of  the  file 
to  be  operated  on  by  a  file  function.  For  example: 

-rw-rw-r —  1  rasmus  rasmus  33  Jul  1  19:20  script. php 

-rw-r — r—  1  root  root  1116  May  26  18:01  /etc/passwd 

Running  this  script.php 

<?php 

readfile ('  /etc/passwd' ) ; 

?> 

results  in  this  error  when  Safe  Mode  is  enabled: 

Warning:  SAFE  MODE  Restriction  in  effect.  The  script  whose  uid  is  500  is  not 
allowed  to  access  /etc/passwd  owned  by  uid  0  in  /docroot /script . php  on  line  2 


If  instead  of  safe_mode  you  set  an  open_basedir  directory  then  all  file  operations  will  be  limited  to  files 
under  the  specified  directory.  For  example  (Apache  httpd.conf  example): 

<Directory  /docroot> 

php_admin_value  open_basedir  /docroot 
</Directory> 


If  you  run  the  same  script.php  with  this  open_basedir  setting  then  this  is  the  result: 

Warning:  open_basedir  restriction  in  effect.  File  is  in  wrong  directory  in 
/docroot/script . php  on  line  2 


You  can  also  disable  individual  functions.  If  we  add  this  to  our  php. ini  file: 
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disable_functions  readfile, system 


Then  we  get  this  output: 

Warning:  readfile ()  has  been  disabled  for  security  reasons  in 
/docroot/script .php  on  line  2 


Functions  restricted/disabled  by  Safe  Mode 

This  is  a  still  probably  incomplete  and  possibly  incorrect  listing  of  the  functions  limited  by  Safe  Mode 


Tabla  23-1.  Safe  Mode  limited  functions 


Function 

Limitations 

dbmopen  1) 

Checks  whether  the  file(s)/directories  you  are  about 
to  operate  on,  have  the  same  UID  as  the  script  that  is 
being  executed. 

dbase_open) 

Checks  whether  the  file(s)/directories  you  are  about 
to  operate  on,  have  the  same  UID  as  the  script  that  is 
being  executed. 

filepro ') 

Checks  whether  the  file(s)/directories  you  are  about 
to  operate  on,  have  the  same  UID  as  the  script  that  is 
being  executed. 

filepro_rowcountO 

Checks  whether  the  file(s)/directories  you  are  about 
to  operate  on,  have  the  same  UID  as  the  script  that  is 
being  executed. 

filepro_retrieve ') 

Checks  whether  the  file(s)/directories  you  are  about 
to  operate  on,  have  the  same  UID  as  the  script  that  is 
being  executed. 

ifx*() 

sql safe mode  restrictions,  (!=  Safe  Mode) 

ingres*() 

sql safe mode  restrictions,  (!=  Safe  Mode) 

mysql*() 

sql safe mode  restrictions,  (!=  Safe  Mode) 

pg_loimport() 

Checks  whether  the  file(s)/directories  you  are  about 
to  operate  on,  have  the  same  UID  as  the  script  that  is 
being  executed. 

posixmkbfo') 

Checks  whether  the  directory  in  which  you  are 
about  to  operate,  has  the  same  UID  as  the  script  that 
is  being  executed. 

putenv  3 

Obeys  the  safe_mode_protected_env_vars  and 
safe_mode_allowed_env_vars  ini-directives.  See 
also  the  documentation  on  putenv) 
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Function 

Limitations 

move_uploaded_file() 

Checks  whether  the  file(s)/directories  you  are  about 
to  operate  on,  have  the  same  UID  as  the  script  that  is 
being  executed. 

chdir') 

Checks  whether  the  directory  in  which  you  are 
about  to  operate,  has  the  same  UID  as  the  script  that 
is  being  executed. 

dl() 

This  functions  is  disabled  in  safe-mode 

backtick  operator 

This  functions  is  disabled  in  safe-mode 

shell exec()  (functional  equivalent  of  backticks) 

This  functions  is  disabled  in  safe-mode 

exec') 

You  can  only  execute  executables  within  the 
safe_mode_exec_dir  For  practical  reasons  it’s 
currently  not  allowed  to  have  .  .  components  in  the 
path  to  the  executable. 

system ') 

You  can  only  execute  executables  within  the 
safe_mode_exec_dir  For  practical  reasons  it’s 
currently  not  allowed  to  have  .  .  components  in  the 
path  to  the  executable. 

passthru') 

You  can  only  execute  executables  within  the 
safe_mode_exec_dir  For  practical  reasons  it’s 
currently  not  allowed  to  have  .  .  components  in  the 
path  to  the  executable. 

popen) 

You  can  only  execute  executables  within  the 
safe_mode_exec_dir  For  practical  reasons  it’s 
currently  not  allowed  to  have  .  .  components  in  the 
path  to  the  executable. 

mkdir') 

Checks  whether  the  directory  in  which  you  are 
about  to  operate,  has  the  same  UID  as  the  script  that 
is  being  executed. 

rmdir') 

Checks  whether  the  file(s)/directories  you  are  about 
to  operate  on,  have  the  same  UID  as  the  script  that  is 
being  executed. 

rename') 

Checks  whether  the  file(s)/directories  you  are  about 
to  operate  on,  have  the  same  UID  as  the  script  that  is 
being  executed.  Checks  whether  the  directory  in 
which  you  are  about  to  operate,  has  the  same  UID  as 
the  script  that  is  being  executed. 

unlink') 

Checks  whether  the  file(s)/directories  you  are  about 
to  operate  on,  have  the  same  UID  as  the  script  that  is 
being  executed.  Checks  whether  the  directory  in 
which  you  are  about  to  operate,  has  the  same  UID  as 
the  script  that  is  being  executed. 
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Function 

Limitations 

copy;) 

Checks  whether  the  file(s)/directories  you  are  about 
to  operate  on,  have  the  same  UID  as  the  script  that  is 
being  executed.  Checks  whether  the  directory  in 
which  you  are  about  to  operate,  has  the  same  UID  as 
the  script  that  is  being  executed,  (on  source  and 
target) 

chgrpp 

Checks  whether  the  file(s)/directories  you  are  about 
to  operate  on,  have  the  same  UID  as  the  script  that  is 
being  executed. 

chownO 

Checks  whether  the  file(s)/directories  you  are  about 
to  operate  on,  have  the  same  UID  as  the  script  that  is 
being  executed. 

chmodO 

Checks  whether  the  file(s)/directories  you  are  about 
to  operate  on,  have  the  same  UID  as  the  script  that  is 
being  executed.  In  addition,  you  cannot  set  the 
SUID,  SGID  and  sticky  bits 

touch;) 

Checks  whether  the  file(s)/directories  you  are  about 
to  operate  on,  have  the  same  UID  as  the  script  that  is 
being  executed.  Checks  whether  the  directory  in 
which  you  are  about  to  operate,  has  the  same  UID  as 
the  script  that  is  being  executed. 

symlink) 

Checks  whether  the  file(s)/directories  you  are  about 
to  operate  on,  have  the  same  UID  as  the  script  that  is 
being  executed.  Checks  whether  the  directory  in 
which  you  are  about  to  operate,  has  the  same  UID  as 
the  script  that  is  being  executed,  (note:  only  the 
target  is  checked) 

link;) 

Checks  whether  the  file(s)/directories  you  are  about 
to  operate  on,  have  the  same  UID  as  the  script  that  is 
being  executed.  Checks  whether  the  directory  in 
which  you  are  about  to  operate,  has  the  same  UID  as 
the  script  that  is  being  executed,  (note:  only  the 
target  is  checked) 

getallheadersO 

In  Safe  Mode,  headers  beginning  with 
’authorization’  (case-insensitive)  will  not  be 
returned.  Warning:  this  is  broken  with  the  aol-server 
implementation  of  getallheaders ;) ! 

Any  function  that  uses 

php4 /main/ f open_wrapper s . c 

?? 
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apache_lookup_uri  (PHP  3>=  3.0.4,  PHP  4  >=  4.0.0) 


Apache 


Efectua  una  peticion  parcial  a  la  URI  especificada  y  devuelve  toda  la  informacion  sobre  ella. 

class  apache_lookup_uri  (string  filename) 


Esta  funcion  efectua  una  llamada  parcial  a  URI.  Esta  llamada  no  hace  sino  obtener  toda  la  informacion 
importante  sobre  el  recurso  pedido  y  la  devuelve  en  un  tipo  clase  .Las  propiedades  de  esa  clase  son: 
status 

the_request 

status_line 

method 

content_type 

handler 

uri 

filename 

path_info 

args 

boundary 

no_cache 

no_local_copy 

allowed 

send_bodyct 

bytes_sent 

byterange 

clength 

unparsed_uri 

mtime 

request_time 


Nota:  Nota:  apache_lookup_uri  solo  funciona  cuando  el  PHP  esta  instalado  como  module  del 
Apache. 


apache_note  (PHP  3>=  3.0.2,  PHP  4  >=  4.0.0) 

Recibe  y  establece  los  valores  de  una  peticion  en  una  tabla  de  notas  del  Apache 

string  apache_note  (string  note_name,  string  [note_value] ) 


apache_note()  es  una  funcion  especffica  del  Apache  que  recibe  y  establece  valores  de  la  peticion  en  una 
tabla  de  notas.  Si  se  llama  con  un  solo  parametro,devuelve  el  valor  de  note_name.  Si  se  llama  con 
dos  parametros,  establece  el  valor  de  note_value  en  note_value  y  devuelve  el  valor  que  habfa  en 
note_name. 
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getallheaders  (php 3  php 4 >=  4 .0 .0) 


Apache 


Recibe  todas  las  cabeceras  de  una  peticion  HTTP 


array  getallheaders (void)  ; 


Esta  funcion  devuelve  asociados  en  un  vector  todas  las  cabeceras  de  la  actual  peticion  HTTP. 

Nota:  Tambien  puedes  obtener  los  valores  de  las  variables  de  los  CGIs  mediante  variables  de 
entorno,  que  funcionan,  este  o  no  el  PHP  funcionando  como  modulo  del  Apache.  Utiliza 
phpinfo))para  ver  una  lista  de  todas  las  variables  de  entorno  definidas  de  esta  forma. 


Ejemplo  1.  ObtenerTodaslasCabecerasO  Ejemplo 

$cabeceras  =  getallheaders () ; 

while  (list ($cabecera,  $valor)  =  each ( $cabeceras ) )  f 
echo  "$cabecera:  $valor<br>\n" ; 

} 


Este  ejemplo  visualiza  todas  las  cabeceras  de  la  peticion  actual. 


Nota:  ObtenerTodaslasCabecerasO  actualmente  solo  funcionara  si  el  PHP  es  cargado  como 
modulo  del  Apache  . 


virtual  (PHP  3,  PHP  4  >=4.0.0) 

Ejecuta  una  sub-peticion  al  Apache 

int  virtual  (string  filename) 


virtual()  es  una  funcion  especffica  del  Apache  que  es  equivalente  a  <!—  #include  virtual...— >  en 
mod_include.  Esto  ejecuta  una  sup-peticion  al  Apache  .Esto,  es  util  para  incluir  CGI-scripts  o  paginas 
.shtml  o  cualquier  tipo  de  fichero  que  puedas  procesar  mediante  el  Apache.  Los  CGI-scripts  deberan 
generar  cabeceras  validas.  Esto,  implica  como  minimo  un  include  ))  6  un  require  );  La  funcion  virtual() 
no  puede  ser  usada  para  incluir  un  documento  que  sea  por  si  mismo  un  documento  PHP. 
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array  (unknown) 


Matrices 


Crear  una  matriz 


array  array (...); 


Devuelve  una  matriz  con  los  parameters  que  se  le  pasan.  A  dichos  parameters  se  les  puede  dar  un  fndice 
usando  el  operador  =>. 

Nota:  array()  es  una  construccion  del  lenguaje  que  se  utiliza  para  representar  matrices  literales,  no 
una  funcion  regular. 


El  siguiente  ejemplo  demuestra  como  crear  una  matriz  bidimensional,  como  especificar  claves  para 
matrices  asociativas,  y  como  especificar  indices  no  consecutivos  en  matrices  normales. 

Ejemplo  1.  Ejemplo  de  array() 

$frutas  =  array  ( 

"frutas"  =>  array ( "a"=> "naranja" ,  "b"=>"platano"  ,  "c"=>"manzana" )  , 
"numeros"  =>  array  (1,  2,  3,  4,  5,  6), 

"hoyos"  =>  array ( "primero" ,  5  =>  "segundo",  "tercero") 

)  ; 


Vea  tambien:  list  3. 


array_count_values  (php  4  >=  4.0.0 

Cuenta  todos  los  valores  de  una  matriz 

array  array_count_values  (array  entrada) 


array_count_values()  devuelve  una  matriz  usando  los  valores  de  la  matriz  entrada  como  claves  y  su 
frecuencia  de  aparicion  en  la  entrada  como  valores. 
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Ejemplo  1.  Ejemplo  de  array_count_values() 

$matriz  =  array (1,  "hola",  1,  "mundo",  "hola"); 

array_count_values ( $matriz ) ;  //  devuelve  array(l=>2,  "hola"=>2,  "mundo"=>l) 


Nota:  Esta  funcion  fue  anadida  en  el  PHP  4.0. 


array_flip(PHP4>=4oo) 

Intercambia  los  valores  de  una  matriz 


array  array_flip  (array  trans) 


array_flip()  devuelve  una  matriz  con  los  valores  intercambiados. 


Ejemplo  1.  Ejemplo  de  array_flip() 

$trans  =  array_flip  ($trans); 
$original  =  strtr  ($str,  $trans); 


Nota:  Esta  funcion  fue  anadida  en  el  PHP  4.0. 


array_keys  <php  4  >=  4  o  o> 

Devuelve  todas  las  claves  de  una  matriz 

array  array_keys  (array  entrada,  mixed  [val_a_buscar] ) 

array_keys()  devuelve  las  claves,  numericas  y  de  cadena,  de  la  matriz  entrada. 

Si  se  especifica  el  parametro  opcional  val_a_buscar,  solo  se  devuelven  las  claves  para  dicho  valor. 
De  otro  modo,  se  devuelven  todas  las  claves  de  la  entrada. 
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Ejemplo  1.  Ejemplo  de  array_keys() 


$matriz  =  array (0  =>  100,  "color"  =>  "rojo"); 

array_keys  ($matriz) ;  //  devuelve  array  (0,  "color") 


$matriz  =  array (1,  100,  2,  100); 

array_keys  ($matriz,  100);  //  devuelve  array  (0,  2) 


Vea  tambien:  array  _valuesO- 

Nota:  Esta  funcion  fue  anadida  en  el  PHP  4.0. 


array_merge  (PHP  4  >=  4.0.0) 


Combina  dos  o  mas  matrices 


array  array_merge  (array  matrlzl,  array  matriz2  [,  ...]) 


array_merge()  combina  los  elementos  de  dos  o  mas  matrices  conjuntamente  de  modo  que  los  valores  de 
una  son  agregados  al  final  de  los  valores  de  la  anterior.  Devuelve  la  matriz  resultante. 

Si  las  matrices  de  entrada  tienen  las  mismas  claves  de  cadena,  el  ultimo  valor  para  cada  clave 
reemplazara  el  valor  previo  de  la  misma.  Si,  por  el  contrario,  las  matrices  tienen  la  misma  clave 
numerica,  esto  no  pasa  y  los  valores  son  simplemente  agregados. 


Ejemplo  1.  Ejemplo  de  array_merge() 

$matrizl  =  array  ("color"  =>  "rojo",  2,  4); 

$matriz2  =  array  ("a",  "b",  "color"  =>  "verde",  "forma"  =>  "trapezoide" ) ; 

array_merge  ($matrizl,  $matriz2); 

La  matriz  resultante  serfa  array("color"  =>  "verde",  2,  4,  "a",  "b",  "forma"  =>  "trapezoide"). 


Nota:  Esta  funcion  fue  anadida  en  el  PHP  4.0. 
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array_pad  (php4>=4.o.o) 

Rellena  una  matriz  con  un  valor  hasta  el  tamano  especificado 

array  array_pad  (array  entrada,  int  tama_relleno ,  mixed  valor_relleno) 


array_pad()  Devuelve  una  copia  de  la  entrada  rellenada  hasta  el  tamano  tama_relleno  con  el 
valor  valor_relleno.  Si  tama_relleno  es  positivo,  entonces  la  matriz  es  rellenada  por  la 
derecha,  y  si  es  negativo,  por  la  izquierda.  Si  el  valor  absoluto  de  tama_relleno  es  menor  o  igual  que 
el  tamano  de  la  entrada  no  se  produce  relleno  alguno. 


Ejemplo  1.  Ejemplo  de  array_pad() 

$entrada  =  array  (12,  10,  9) ; 


$resultado  =  array_pad 

( $entrada, 

5, 

0)  ; 

//el  resultado  es  array  (12,  10, 

9, 

0,  0) 

$resultado  =  array_pad 

( $entrada, 

-7 , 

-l)  ; 

//  el  resultado  es  array  (-1,  -1, 

-1, 

-1,  12 

$resultado  =  array_pad 
//  no  rellenado 

( $entrada, 

2, 

"no") ; 

array_pop  (PHP  4  >=  4.0.0) 

Extrae  el  ultimo  elemento  de  la  matriz 

mixed  array_pop  (array  matriz) 

array_pop()  extrae  y  devuelve  el  ultimo  valor  de  la  matriz,  acortando  la  matriz  en  un  elemento. 

Ejemplo  1.  Ejemplo  de  array_pop() 

$pila  =  array  ("naranja",  "manzana",  " f rambuesa" )  ; 

$fruta  =  array_pop  ($pila) ; 

Tras  esto,  $pila  contiene  solo  2  elementos:  "naranja"  y  "manzana",  y  Sfruta  contiene  "frambuesa". 
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Vea  tambien:  array  _push\),  array_shift'),  y  array_unshift  '). 
Nota:  Esta  funcion  fue  anadida  en  el  PHP  4.0. 


array_push  (php  4  >=  4 .0 .0) 

Inserta  uno  o  mas  elementos  al  final  de  la  matriz 


int  array  push  (array  matriz,  mixed  var  [,  ...]) 


array_push()  considera  a  la  matriz  como  una  pila,  e  inserta  las  variables  que  se  le  pasan  al  final  de  la 
matriz.  La  longitud  de  la  matriz  se  incrementa  en  el  numero  de  variables  insertadas.  Tiene  el  mismo 
efecto  que  ejecutar: 

$matriz[]  =  $var; 


para  cada  var. 

Devuelve  el  nuevo  numero  de  elementos  de  la  matriz. 


Ejemplo  1.  Ejemplo  de  array_push() 

$pila  =  array  (1,  2); 
array_push ( $pila,  3); 


Este  ejemplo  dejara  $pila  conteniendo  4  elementos:  1,  2, y  3. 
Vea  tambien:  array _pop0,  array_shift(),  y  array _unshift  ')- 

Nota:  Esta  funcion  fue  anadida  en  el  PHP  4.0. 


array_reverse  (PHP  4  >=  4.0.0) 


Devuelve  una  matriz  con  los  elementos  en  orden  inverso 
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array  array_reverse  (array  matriz) 


array_reverse()  toma  la  matriz  de  entrada  y  devuelve  una  nueva  matriz  con  los  elementos  en  orden 
inverso. 


Ejemplo  1.  Ejemplo  de  array_reverse() 

$entrada  =  array  ("php",  4.0,  array  ("verde",  "rojo")); 
$resultado  =  array_reverse  ($entrada) ; 

Esto  hace  que  $resultado  contenga  array  (array  ("verde",  "rojo"),  4.0,  "php"). 


Nota:  Esta  funcion  fue  anadida  en  PHP  4.0  Beta  3. 


array_shift  (php4>=4.o.o) 


Extrae  un  elemento  del  comienzo  de  la  matriz 


mixed  array_shift  (array  matriz) 


array_shift()  extrae  el  primer  valor  de  la  matriz  y  lo  devuele,  acortando  la  matriz  en  un  elemnto  y 
moviendo  todo  hacia  arriba. 


Ejemplo  1.  Ejemplo  de  array_shift( ) 

$args  =  array  ("-v",  "-f"); 

$opcion  =  array_shift  ($args) ; 


Esto  da  como  resultado  que  $args  tenga  como  elemento  restante  "-f"  y  que  $opcion  valga  "-v". 
Vea  tambien:  array _unshift(),  array _pushQ,  y  array _pop'). 

Nota:  Esta  funcion  fue  anadida  en  el  PHP  4.0. 
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array_slice  (php4>=4.o.o) 


Extrae  una  porcion  de  la  matriz 


array  array_slice  (array  matriz,  int  desplazamiento,  int  [tamano] ) 


array_slice()  devuelve  una  secuencia  de  elementos  de  la  matriz  especificada  por  los  parametros 

desplazamiento  y  tamano. 

Si  el  desplazamiento  es  positivo,  la  secuencia  comenzara  en  dicha  posicion  de  la  matriz.  Si  el 
desplazamiento  es  negativo,  la  secuencia  comenzara  en  esa  posicion  desde  el  final  de  la  matriz. 

Si  se  especifica  el  tamano  y  este  es  positivo,  la  secuencia  contendra  tantos  elementos  como  se  diga  en 
el.  Si  fuese  negativo,  la  secuencia  se  detendra  a  tantos  elementos  del  final  de  la  matriz.  Si  se  omite,  la 
secuencia  contendra  todos  los  elementos  desde  el  desplazamiento  hasta  el  final  de  la  matriz. 


Ejemplo  1.  Ejemplo  de  array_slice()  examples 

$entrada  =  array  ("a",  "b",  "c",  "d",  "e"); 


$salida  = 

array_slice 

($entrada, 

2)  ; 

// 

devuelve 

ll  n  " 

r 

"d",  y  "e" 

$salida  = 

array_slice 

( $entrada. 

2,  -1); 

// 

devuelve 

ii  n  n 

t 

"d" 

$salida  = 

array_slice 

( $entrada. 

-2,  1); 

// 

devuelve 

"d" 

$salida  = 

array_slice 

( $entrada. 

0,  3); 

// 

devuelve 

II  II 

^  , 

"b",  y  "c" 

Vea  tambien:  array _splice '). 

Nota:  Esta  funcion  fue  anadida  en  el  PHP  4.0. 


array_splice  php  4  >=  4.0.0) 

Suprime  una  porcion  de  la  matriz  y  la  sustituye  por  otra  cosa 

array  array_splice  (array  entrada,  int  desplazamiento  [,  int  tamano,  array 
[ sustitucion] ] ) 


array_splice()  suprime  los  elementos  designados  por  el  desplazamiento  y  el  tamano  de  la  matriz 
entrada,  y  los  sustituye  con  los  elementos  de  la  matriz  de  sustitucion  si  se  especifica. 
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Si  el  desplazamiento  es  positivo,  el  comienzo  de  la  parte  suprimida  serfa  en  esa  posicion  desde  el 
comienzo  de  la  matriz  de  entrada.  Si  el  desplazamiento  es  negativo,  se  cuenta  la  posicion  desde 
el  final  de  la  matriz  de  entrada. 

Si  se  omite  tamano,  se  suprime  todo  desde  el  desplazamiento  hasta  el  final  de  la  matriz.  Si  se 
especifica  el  tamano  y  es  positivo,  se  suprimiran  tantos  elementos  como  se  especifica.  Si  fuera  negativo, 
el  final  de  la  porcion  eliminada  estara  a  tantos  elementos  del  final  de  la  matriz.  Tmco:  para  eliminar  todo 
desde  el  desplazamiento  hasta  el  final  de  la  matriz  cuando  tambien  se  especifica  sustitucion, 
utilice  count  ($entrada)  como  tamano. 

Si  se  especifia  la  matriz  de  sustitucion,  entonces  los  elementos  suprimidos  son  reemplazados  con 
los  elementos  de  dicha  matriz.  Si  los  valores  de  desplazamiento  y  tamano  son  tales  que  nada  es 
borrado,  los  elementos  de  la  matriz  sustitucion  se  insertaran  en  la  posicion  indicada  por  el 
desplazamiento.  Truco:  si  solo  se  va  a  sustituir  algo  por  un  elemento  nada  mas,  no  hace  falta  poner 
array  ( )  alrededor  del  mismo,  salvo  que  dicho  elemento  sea  una  matriz  en  sf  mismo. 

Las  siguientes  funciones  son  equivalentes: 

array_push ( $entrada,  $x,  $y)  array_splice ( $entrada,  count ($entrada) ,  0,  ar¬ 

ray  ($x,  $y) ) 

array_pop ($entrada)  array_splice ( $entrada,  -1) 

array_shift ($entrada)  array_splice ( $entrada,  0,  1) 

array_unshift ( $entrada,  $x,  $y)  array_splice ( $entrada,  0,  0,  array ($x,  $y) ) 
$a[$x]  =  $y  array_splice ( $entrada,  $x,  1,  $y) 


Devuelve  una  matriz  que  tiene  los  elementos  eliminados 


Ejemplo  1.  Ejemplos  de  array_splice() 


$entrada  =  array ( "ro jo" ,  "verde",  "azul",  "amarillo"); 


array_splice ($entrada, 
array_splice ($entrada, 
array_splice ($entrada, 

array_splice ($entrada. 


2);  //  $entrada  vale  ahora  array (" ro jo" ,  "verde") 

1,  -1);  //  $entrada  vale  ahora  array (" ro jo" ,  "amarillo") 
1,  count ($entrada) ,  "naranja"); 

//  $entrada  vale  ahora  array  (  "ro jo" ,  "naranja") 

-1,  1,  array ( "negro" ,  "marron'j  ) ; 

//  $entrada  vale  ahora  array  (  "ro jo" ,  "verde", 

//  "azul",  "negro",  "marron") 


Vea  tambien:  array _slice(). 

Nota:  Esta  funcion  fue  anadida  en  el  PHP  4.0. 
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array_unshift  (php  4  >=  4.0.0 

Introduce  uno  o  mas  elementos  al  principio  de  la  matriz 

int  array_unshift  (array  matriz,  mixed  var,  [...]) 


array_unshift()  anade  los  elementos  que  se  le  pasan  al  principio  de  la  matriz.  Notese  que  la  lista  de 
elementos  es  anadida  como  un  todo,  de  modo  que  los  elementos  anadidos  mantienen  su  orden. 

Devuelve  el  numero  de  elementos  en  la  matriz. 

Ejemplo  1.  Ejemplo  de  array_unshift( ) 

$cola  =  array  ("pi",  "p3"); 

array_unshif t ( $cola,  "p4",  "p5",  "p6"); 

Esto  hara  que  $cola  contenga  5  elementos:  "p4",  "p5",  "p6",  "pi",  y  "p3". 

Vea  tambien:  array  _shift '),  array_push '),  y  array_pop\). 

Nota:  Esta  funcion  fue  anadida  en  el  PHP  4.0. 


array_values  <php  4  >=  4.0.0 

Devuelve  todos  los  valores  de  una  matriz 


array  array_values  (array  entrada ) 


array_values()  devuelve  todos  los  valores  de  la  matriz  entrada. 


Ejemplo  1.  Ejemplo  de  array_values() 

$matriz  =  array  ( "talla"  =>  "XL",  "color"  =>  "dorado"); 
array_values ( Smatriz )  ;  //  devuelve  array ("XL",  "dorado") 


Nota:  Esta  funcion  fue  anadida  en  el  PHP  4.0. 
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array_walk  (PHP  3>=  3.0.3,  PHP  4  >=  4.0.0) 

Aplica  una  funcion  del  usuario  a  cada  elemento  de  una  matriz. 

int  array_walk  (array  matriz,  string  func,  mixed  datosvarios) 


Aplica  la  funcion  llamada  func  a  cada  elemento  de  la  matri  z.  La  funcion  func  recibira  el  valor  de  la 
matriz  como  primer  parametro  y  la  clave  como  segundo.  Si  se  proporciona  el  parametro  datosvarios 
sera  pasado  como  tercer  parametro  a  la  funcion  de  usuario. 

Si  func  necesita  mas  de  dos  o  3  argumentos,  dependiendo  de  datosvarios,  se  generara  un  aviso 
cada  vez  que  array_walk()  llama  a  func.  Estos  avisos  pueden  suprimirse  si  se  pone  ’  antes  de  la 
llamada  a  array_walk(),  o  usando  la  funcion  error_reportingO- 

Nota:  Si  func  precisa  trabajar  con  los  valores  reales  de  la  matriz,  especifique  que  el  valor  del 
primer  parametro  de  func  debe  pasarse  por  referenda.  Desde  ese  instante,  los  cambios  realizados 
sobre  dichos  elementos  tambien  seran  realizados  en  la  propia  matriz. 


Nota:  El  pasar  la  clave  y  los  datos  de  usuario  a  func  fue  una  caracterlstica  anadida  en  PHP  4.0. 

En  PHP  4  se  debe  llamar  reset;)  las  veces  necesarias,  pues  array_walk()  no  reajusta  la  matriz  por 
defecto. 


Ejemplo  1.  Ejemplo  de  array_walk() 

$frutas  =  array  ( "d"=>"limon" ,  "a"=>"naran ja" ,  "b"=>"platano" ,  "c"=>"manzana" ) 

function  test_alterar  (&$iteml,  $clave,  $prefix)  { 

$iteml  =  "Sprefix:  $iteml"; 

} 

function  test_ver  ($item2,  $clave)  { 
echo  "$clave.  $item2<br>\n" ; 

} 

array_walk  ($frutas,  'test_ver'); 
reset  ($frutas) ; 

array_walk  ($frutas,  ' test_alterar ' ,  ' fruta' ) ; 

reset  ($frutas) ; 

array_walk  ($frutas,  'test_ver'); 
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Vea  tambien:  each')  y  list;). 


arsort  (PHP  3,  PHP  4  >=  4.0.0) 


Ordena  una  matriz  en  orden  inverso  y  mantiene  la  asociacion  de  indices 


void  arsort  (array  matriz) 


Esta  funcion  ordena  una  matriz  de  modo  que  los  indices  mantengan  su  correlacion  con  los  elementos  de 
la  misma  a  los  que  estan  asociados.  Esto  se  utiliza  principalmente  para  ordenar  matrices  asociativas  en 
las  que  el  orden  de  los  elementos  es  importante. 

Ejemplo  1.  Ejemplo  de  arsortQ 

$frutas  =  array  ( "d"=>" limon" ,  " a"=>"naran ja" ,  "b"=>"platano" ,  "c"=>"manzana" ) 

arsort  ($frutas) ; 

for  (reset  ($frutas) ;  $clave  =  key  ($frutas) ;  next  ($frutas) )  { 

echo  " f rutas [ $clave ]  =  " . $f rutas [ $clave ] . " \n" ; 

} 


Este  ejemplo  mostrarfa:  f rutas  [b]  =  platano  frutas[a]  =  naranja  frutas [c]  = 
manzana  frutas  [d]  =  limon  Las  frutas  han  sido  ordenadas  en  orden  alfabetico  inverso  y  los 
indices  asociados  con  cada  elemento  se  han  mantenido. 

Vea  tambien:  asort;),  rsorb),  ksort;),  y  sort)). 


asort  (PHP  3,  PHP  4  >=4.0.0) 

Ordena  una  matriz  y  mantiene  la  asociacion  de  indices 

void  asort  (array  matriz) 


Esta  funcion  ordena  una  matriz  de  modo  que  los  indices  mantengan  su  correlacion  con  los  elementos  de 
la  misma  a  los  que  estan  asociados.  Esto  se  utiliza  principalmente  para  ordenar  matrices  asociativas  en 
las  que  el  orden  de  los  elementos  es  importante. 
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Ejemplo  1.  Ejemplo  de  asort() 

$frutas  =  array  ( "d"=>" limon" ,  " a"=>"naran ja" ,  "b"=>"platano" ,  "c"=>"manzana" ) 

asort  ($frutas) ; 

for  (reset  ($frutas) ;  $clave  =  key  ($frutas) ;  next  (Sfrutas) )  { 

echo  " f rutas [ $clave ]  =  " . $f rutas [ $clave ] . " \n" ; 

} 


Este  ejemplo  mostrara:  frutasfd]  =  limon  frutasfa]  =  naranja  frutas[c]  =  manzana 
frutas[d]  =  platano  Las  frutas  han  sido  ordenadas  en  orden  alfabetico  y  los  indices  asociados  con 
cada  elemento  se  han  mantenido. 

Vea  tambien:  arsort)),  rsort'j,  ksort)),  y  sort'). 


)act  (PHP  4  >=  4.0.0) 


Crea  una  matriz  que  contiene  variables  y  sus  valores 


array  compact  (string  nombrevar  /  array  nombrevars  [,  ...]) 


compact()  toma  un  numero  variable  de  parametros.  Cada  uno  puede  ser  tanto  una  cadena  que  contiene  el 
nombre  de  la  variable,  como  una  matriz  de  nombres  de  variable.  La  matriz  puede  contener  otras  matrices 
de  nombres  de  variable  en  su  interior;  compact()  los  procesa  recursivamente. 

Para  cada  uno  de  estos,  compact!)  busca  una  variable  con  dicho  nombre  en  la  tabla  de  slmbolos  y  la 
anade  a  la  matriz  de  salida  de  modo  que  el  nombre  de  la  variable  es  la  clave  y  el  contenido  de  esta  es  el 
valor  para  dicha  clave.  Para  resumir,  hace  lo  contrario  de  extract))-  Devuelve  la  matriz  de  salida  con  las 
variables  anadidas  a  la  misma. 


Ejemplo  1.  Ejemplo  de  compact!) 

$ciudad  =  "San  Francisco"; 

Sestado  =  "CA"; 

$evento  =  "SIGGRAPH"; 

$location_vars  =  array  ("ciudad",  "estado"); 

$resultado  =  compact  ("evento",  $location_vars) ; 

Tras  esto,  $resultado  valdra  array  ("evento"  =>  "SIGGRAPH",  "ciudad"  =>  "San  Lrancisco",  "estado"  => 
"CA"). 


Vea  tambien:  extract))- 
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Nota:  Esta  funcion  fue  anadida  en  el  PHP  4.0. 


count  (PHP  3,  PHP  4  >=  4.0.0) 

Cuenta  los  elementos  de  una  variable 


int  count  (mixed  var) 


Devuelve  el  numero  de  elementos  en  var,  que  tipicamente  es  una  matriz  (porque  cualquier  otra  cosa 
tendrfa  solo  un  elemento). 

Devuele  1  si  la  variable  no  es  una  matriz. 

Devuelve  0  si  la  variable  no  tiene  valor. 


Aviso 

count()  puede  devolver  0  para  una  variable  sin  valor,  pero  tambien  puede  devolver 
0  para  una  variable  ya  inicializada  pero  con  una  matriz  vacla.  Utilice  isset[)  para 
comprobar  si  una  variable  esta  inicializada. 


Vea  tambien:  sizeofQ,  issetQ,  y  is_array(). 


current  (PHP  3,  PHP  4  >=  4.0.0) 

Devuelve  el  elemento  actual  de  una  matriz 


mixed  current  (array  matriz) 


Cada  matriz  tiene  un  puntero  interno  al  elemento  "actual",  que  se  inicializa  al  primer  elemento  insertado 
en  la  misma. 

La  funcion  current()  simplemente  devuelve  el  elemento  de  la  tabla  al  que  apunta  el  puntero  interno.  No 
mueve  el  puntero  de  ninguna  manera.  Si  el  puntero  interno  apunta  fuera  del  final  de  la  lista  de  elementos, 
currentQ  devuelve  false. 
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Aviso 

Si  la  matriz  contiene  elementos  vacios  (0  6  la  cadena  vacla)  esta  funcion 
devolvera  false  tambien  para  dichos  elementos.  Esto  hace  imposible  determinar 
si  se  esta  realmente  al  final  de  la  lista  en  tales  matrices  usando  current().  Para 
recorrer  adecuadamente  una  matriz  que  pueda  contener  elementos  vacfos,  utilice 
la  funcion  each;). 


Vea  tambien:  end;),  next;),  prev()  y  reset;). 


each  (PHP  3,  PHP  4  >=  4.0.0) 

Devuelve  el  siguiente  par  clave/valor  de  una  matriz 

array  each  (array  matriz) 


Devuelve  el  par  clave/valor  actual  para  la  mat ri z  y  avanza  el  cursor  de  la  misma.  Esta  pareja  se 
devuele  en  una  matriz  de  4  elementos,  con  las  claves  0 ,  1 ,  key ,  y  value.  Los  elementos  0  y  key  contienen 
el  nombre  de  clave  del  elemento  de  la  matriz,  y  1  y  value  contienen  los  datos. 

Si  el  puntero  interno  para  la  matriz  apunta  pasado  el  final  del  contenido  de  la  matriz,  each()  devuelve 

FALSE. 

Ejemplo  1.  Ejemplos  de  each() 

$chorrada  =  array  ("bob",  "fred",  "jussi",  "jouni",  "egon",  "marliese") ; 
$tonteria  =  each  ($chorrada) ; 

$tonteria  contiene  ahora  los  siguientes  pares  clave/valor: 

•  0=>0 

•  1  =>  ’bob’ 

•  key  =>  0 

•  value  =>  ’bob’ 

$chorrada  =  array  ("Robert"  =>  "Bob",  "Seppo"  =>  "Sepi"); 

$tonteria  =  each  ($chorrada) ; 

$tonteria  contiene  ahora  los  siguientes  pares  clave/valor: 

•  0  =>  ’Robert’ 

•  1  =>  ’Bob’ 

•  key  =>  ’Robert’ 

•  value  =>  ’Bob’ 
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each()  se  usa  normalmente  de  forma  conjunta  a  list')  para  recorrer  una  matriz;  por  ejemplo, 
$HTTP_POST_VARS: 

Ejemplo  2.  Recorriendo  $HTTP_POST_VARS  con  each() 

echo  "Valores  enviados  con  el  metodo  POST:<br>"; 
reset  ($HTTP_POST_VARS) ; 

while  (list  ($clave,  $val)  =  each  ($HTTP_POST_VARS) )  { 

echo  "$clave  =>  $val<br>"; 

} 


Cuando  se  ha  ejecutado  each(),  el  cursor  de  la  matriz  quedara  en  el  siguiente  elemento  de  la  misma,  o  en 
el  ultimo  si  llega  al  final  de  esta. 

Vea  tambien:  key '),  list'),  current'),  reset'),  next'),  y  prevQ. 

end  (PHP3,  PHP  4  >=  4.0.0) 

Mueve  el  puntero  interno  de  una  tabla  al  ultimo  elemento 

end  (array  matriz) 

end()  avanza  el  puntero  interno  de  la  matriz  al  ultimo  elemento. 

Vea  tambien:  current'),  each;),  end(),  next;),  y  reset;). 

extract  (PHP  3>=  3.0.7,  PHP  4  >=  4.0.0) 

Importa  variables  a  la  tabla  de  simbolos  desde  una  matriz 

void  extract  (array  matriz_vars  [,  int  tipo_extraccion  [,  string  prefijo ]]) 

Esta  funcion  se  utiliza  para  importar  variables  desde  una  matriz  a  la  tabla  de  simbolos  actual.  Toma  la 
matriz  asoiativa  matriz_vars  y  trata  las  claves  como  nombres  de  variable  y  los  valores  como  los 
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valores  de  estas.  Para  cada  par  clave/valor  creara  una  variable  en  la  tabla  de  sfmbolos  actual,  sujeto  a  los 
parametros  tipo_extraccion  y  prefijo. 

extract!)  controla  las  colisiones  con  las  variables  que  ya  existen.  La  forma  de  tratar  estas  se  determina 
por  el  tipo_extraccion.  Puede  tener  unicamente  uno  de  los  siguientes  valores: 

EXTR_OVERWRITE 

Si  hay  colision,  sobreescribe  la  variable  existente. 


EXTR_SKIP 

Si  hay  colision,  no  sobreescribas  la  variable  existente. 
EXTR_PREFIX_SAME 

Si  hay  una  colision,  anade  el  prefijo  a  la  nueva  variable. 

EXTR_PREFIX_ALL 

Anade  el  prefijo  a  todas  las  variables. 


Si  no  se  especifica  tipo_extraccion,  se  asume  que  vale  EXTR_OVERWRITE. 

Notese  que  el  prefijo  solo  se  necisita  si  tipo_extraccion  vale  EXTR_PREFIX_SAME  o 
EXTR_PREFIX_ALL. 

extract!)  comprueba  si  cada  clave  es  un  nombre  valido  de  variable,  y  solo  lo  importa  si  lo  es. 

Nota:  N.T.:  En  el  caso  esparto!  no  valdria  "ano"  como  nombre  variable  (pero  sf  como  clave  en  una 
matriz  cualquiera). 


Un  uso  posible  para  extract  serfa  importar  en  la  tabla  de  sfmbolos  las  variables  contenidas  en  la  matriz 
asociativa  que  devuelve  wddx_deserialize'). 


Ejemplo  1.  Ejemplo  de  extract!) 

<php? 

/*  Suponemos  que  $matriz_var  es  una  matriz  devuelta  por 
wddx_deserialize  */ 

$tamano  =  "grande"; 

$matriz_var  =  array  ("color"  =>  "azul", 

"tamano"  =>  "media", 

"forma"  =>  "esfera") ; 

extract  ( $matriz_var ,  EXTR_PREFIX_SAME,  "wddx"); 
print  "$color,  $tamano,  $forma,  $wddx_tamano\n" ; 

?> 
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El  programa  anterior  producira: 

azul,  grande,  esfera,  media 


La  variable  $tamano  no  fue  sobreescrita  porque  especificamos  EXTR_PREFIX_SAME,  que  provoco  la 
creation  de  $wddx_tamano.  Si  se  hubiera  especificado  EXTR_SKIP,  $wddx_tamano  ni  siquiera  habria 
sido  creada.  EXTR_OVERWRITE  habria  provocado  que  $tamano  tuviera  el  valor  "media",  y 
EXTR_PREFIX_ALL  habria  provocado  que  aparecieran  nuevas  variables  llamadas  $wddx_color, 
$wddx_tamano,  y  $wddx_forma. 


inarray  (PHP  4  >=  4.0.0) 

Devuelve  true  si  un  valor  esta  en  una  matriz 


bool  in_array  (mixed  aguja,  array  pajar) 


Busca  la  aguja  en  el  pajar,  y  devuelve  true  si  se  encuentra  y  false  en  caso  contrario. 


Ejemplo  1.  Ejemplo  de  in_array() 

$os  =  array  ("Mac",  "NT",  "Irix",  "Linux"); 
if  (in_array  ("Irix",  $os) ) 
print  "Encontrado  Irix"; 


Nota:  Esta  funcion  fue  anadida  en  el  PHP  4.0. 


key 


(PHP  3,  PHP  4  >=4.0.0) 


Obtiene  una  clave  de  una  matriz  asociativa 


mixed  key  (array  matriz) 
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Vea  tambien:  current)),  next') 


Matrices 


krsort  (PHP  3>=  3.0.13,  PHP  4  >=  4.0.0) 

Ordena  una  matriz  por  clave  en  orden  inverso 

int  krsort  (array  matriz) 


Ordena  una  matriz  por  clave  en  orden  inverso,  manteniendo  las  correlaciones  clave  a  dato.  Esto  es  util 
principalmente  en  matrices  asociativas. 

Ejemplo  1.  Ejemplo  de  krsort() 

$frutas  =  array  ( "d"=>" limon" ,  " a"=>"naran ja" ,  "b"=>"platano" ,  "c"=>"manzana" ) 

krsort  ($frutas) ; 

for  (reset  ($frutas) ;  $clave  =  key  ($frutas) ;  next  ($frutas) )  { 

echo  " f rutas [ $clave ]  =  " . $f rutas [ $clave ] . " \n" ; 

} 


Este  ejemplo  mostrara:  frutas [d]  =  limon  frutas[c]  =  manzana  frutas[b]  =  platano 
frutas [a]  =  naranja 

Vea  tambien:  asort'),  arsortj),  ksort))  sort'),  y  rsort)). 


ksort  (PHP  3,  PHP  4  >=4.0.0) 


Ordena  una  matriz  por  clave 


int  ksort  (array  matriz) 


Ordena  una  matriz  por  clave,  manteniendo  las  correlaciones  clave  a  dato.  Esto  es  util  principalmente  en 
matrices  asociativas. 

Ejemplo  1.  Ejemplo  de  ksort() 

$frutas  =  array  ( "d"=>"limon" ,  "a"=>"naran ja" ,  "b"=>"platano" ,  "c"=>"manzana" ) 
ksort  ($frutas) ; 

for  (reset  ($frutas) ;  $clave  =  key  ($frutas) ;  next  ($frutas) )  { 

echo  " frutas [ $clave ]  =  $f rutas [ $clave] \n" ; 

} 
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Este  ejemplo  mostrara:  frutas[a]  =  naranja  frutas[b]  =  platano  frutas[c]  =  manzana 
frutas [d]  =  limon 

Vea  tambien:  asort'),  arsort'),  sort  '),  y  rsort'). 


list 


(unknown) 


Asigna  variables  como  si  fueran  una  matriz 


void  list  (...); 


Como  array'),  esta  no  es  realmente  una  funcion,  sino  una  construccion  del  lenguaje.  list()  se  usa  para 
asignar  una  lista  de  variables  en  una  sola  operation. 

Ejemplo  1.  Ejemplo  de  list() 

<table> 

<tr> 

<th>Nombre  empleado</th> 

<th>Sueldo</th> 

</tr> 

<?php 

$resultado  =  mysql ( $conn,  "SELECT  id,  nombre,  salario  FROM  empleados"); 
while  (list($id,  $nombre,  $salario)  =  mysql_fetch_row ($resultado) )  { 

print ("  <tr>\n"  . 

"  <td><a  href=\"info .php3?id=$id\">$nombre</ax/td>\n" . 

"  <td>$salario</td>\n" . 

"  </tr>\n" ) ; 


</table> 


Vea  tambien:  each  !),  array  3. 


next  (PHP  3,  PHP  4  >=  4.0.0) 


Avanza  el  puntero  interno  de  una  matriz 
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mixed  next  (array  matriz) 


Devuelve  el  elemento  de  la  matriz  que  ocupa  el  lugar  siguiente  al  apuntado  por  el  puntero  interno,  o 
false  si  no  hay  mas  elementos. 

next()  se  comporta  como  current  '),  con  una  diferencia.  Avanza  el  puntero  interno  de  la  matriz  en  una 
posicion  antes  de  devolver  el  elemento.  Eso  significa  que  devuelve  el  siguiente  elemento  de  la  matriz  y 
que  avanza  el  puntero  interno  en  uno.  Si  al  avanzar  se  pasa  del  final  de  la  lista  de  elementos,  next() 
devuelve  false. 


Aviso 

Si  la  matriz  contiene  elementos  vacfos,  esta  funcion  tambien  devolvera  false 
para  dichos  elementos.  Para  recorrer  adecuadamente  una  matriz  que  pueda 
contener  elementos  vacios,  vea  la  funcion  each;). 


Vea  tambien:  current;),  end))  prey))  y  reset)) 


pos  (PHP  3,  PHP  4  >=  4.0.0) 

Obtiene  el  elemento  actual  de  una  matriz 

mixed  pos  (array  matriz) 

Este  es  un  alias  para  current)). 

Vea  tambien:  end '),  next)),  prev))  y  reset '). 


prev  (PHP  3,  PHP  4  >=  4.0.0) 

Rebobina  el  puntero  interno  de  una  matriz 

mixed  prev  (array  matriz) 


Devuelve  el  elemento  de  la  matriz  que  esta  en  la  posicion  anterior  a  la  que  apuntaba  previamente  el 
puntero  interno,  o  false  si  no  hay  mas  elementos. 
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Aviso 

Si  la  matriz  contiene  elementos  vacios,  esta  funcion  tambien  devolvera  false 
para  dichos  elementos.  Para  recorrer  adecuadamente  una  matriz  que  puede 
contener  elementos  vacios,  vea  la  funcion  each;). 


prev()  se  comporta  igual  que  next  3,  excepto  que  rebobina  el  puntero  interno  una  position  en  lugar  de 
avanzarlo. 

Vea  tambien:  current;),  end  )  next;)  y  reset)) 


rango  (unknown) 

Crea  una  matriz  que  contiene  un  rango  de  enteros 

array  rango  (int  bajo,  int  alto) 

rango()  devuelve  una  matriz  de  enteros  desde  bajo  hasta  alto,  ambos  inclusive. 
Vea  un  ejemplo  de  su  uso  en  la  funcion  shuffle  ;). 

reset  (PHP3,  PHP  4  >=  4.0.0) 

Fija  el  puntero  interno  de  una  matriz  a  su  primer  elemento 

mixed  reset  (array  matriz) 

reset()  rebobina  el  puntero  interno  de  la  matriz  a  su  primer  elemento. 
reset))  devuelve  el  valor  del  primer  elemento  de  la  matriz. 

Vea  tambien:  current)),  each)),  next)),  prev)),  y  reset)). 

rsort  (PHP  3,  PHP  4  >=4.0.0) 

Ordena  una  matriz  en  orden  inverso 

void  rsort  (array  matriz) 
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Esta  funcion  ordena  una  matriz  en  orden  inverso  (mayor  a  menor). 

Ejemplo  1.  Ejemplo  de  rsort() 

$frutas  =  array  ("limon",  "naranja",  "platano",  "manzana") ; 
rsort  ($frutas) ; 

for  (reset  ($frutas) ;  list  ($clave,  $valor)  =  each  ($frutas) ;  )  { 

echo  " f rutas [ $clave ]  =  ",  $valor,  "\n"; 

} 


Este  ejemplo  mostrara:  frutas[0]  =  platano  frutas[l]  =  naranja  frutas[2] 
f  rut  as  [3]  =  limon  Las  frutas  han  sido  ordenadas  en  orden  alfabetico  inverso. 

Vea  tambien:  arsort')),  asort)),  ksort)),  sort"),  y  usort)). 


shuffle  (PHP  3>=  3.0.8,  PHP  4  >=  4.0.0) 


Mezcla  una  matriz 


void  shuffle  (array  matriz) 


Esta  funcion  mezcla  (cambia  aleatoriamente  el  orden  de  los  elementos  de)  una  matriz. 

Ejemplo  1.  Ejemplo  de  shuffle() 

$numeros  =  range  (1,20); 
srand  (time ( ) ) ; 
shuffle  ($numeros); 

while  (list(,  $numero)  =  each  ($numeros) )  { 

echo  "$numero 

} 


Vea  tambien:  arsort  ),  asort)),  ksortj),  rsort)),  sort')  y  usort)). 


sizeof  (PHP  3,  PHP  4  >=4.0.0) 

Obtiene  el  numero  de  elementos  de  una  matriz 

int  sizeof  (array  matriz) 


manzana 
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Devueve  el  numero  de  elementos  de  la  matriz. 
Vea  tambien:  count  ') 


sort  (PHP  3,  PHP  4  >=  4.0.0) 


Ordena  una  matriz 


void  sort  (array  matriz) 


Esta  funcion  ordena  una  matriz.  Los  elementos  estaran  ordenados  de  menor  a  mayor  cuando  la  funcion 
termine. 

Ejemplo  1.  Ejemplo  de  sort() 

$frutas  =  array  ("limon",  "naranja",  "platano",  "manzana") ; 
sort  ( $f rutas ) ; 

for  (reset  ($frutas) ;  $clave  =  key  ($frutas) ;  next  ($frutas) )  { 

echo  " f rutas [ $clave ]  =  $f rutas [ $clave] \n" ; 

} 


Este  ejemplo  mostrara:  frutas[0]  =  limon  frutas[l]  =  manzana  frutas[2]  =  naranja 
f rutas  [3]  =  platano  Las  frutas  han  sido  ordenadas  en  orden  alfabetico. 

Vea  tambien:  arsortj),  asort'),  ksort'),  rsort'),  y  usortj). 


uasort  (PHP  3>=  3.0.4,  PHP  4  >=  4.0.0) 

Ordena  una  matriz  mediante  una  funcion  de  comparacion  definida  por  el  usuario  y  mantiene  la 
asociacion  de  indices 

void  uasort  (array  matriz,  function  func_comparar) 


Esta  funcion  ordena  una  matriz  de  modo  que  los  indices  de  la  misma  mantengan  su  correlation  con  los 
elementos  a  los  que  estan  asociados.  Esto  se  utiliza  principalmente  para  ordenar  matrices  asociativas  en 
las  que  el  orden  de  los  elementos  es  importante.  La  funcion  de  comparacion  viene  definida  por  el  usuario. 
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uksort  (PHP  3>=  3.0.4,  PHP  4  >=  4.0.0) 

Ordena  una  matriz  por  claves  mediante  una  funcion  definida  por  el  usuario 

void  uksort  (array  matriz,  function  func_comparar) 


Esta  funcion  ordenara  las  claves  de  una  matriz  utilizando  una  funcion  de  comparacion  suministrada  por 
el  usuario.  Si  la  matriz  a  ordenar  necesita  utilizar  un  criterio  poco  trivial,  esta  es  la  funcion  que  debera 
usar. 

Ejemplo  1.  Ejemplo  de  uksort() 

function  micomparar  ($a,  $b)  { 

if  ($a  ==  $b)  return  0; 
return  ($a  >  $b)  ?  -1  :  1; 

} 

$a  =  array  (4  =>  "cuatro",  3  =>  "tres",  20  =>  "veinte",  10  =>  "diez"); 
uksort  ($a,  micomparar); 

while  (list  ($clave,  $valor)  =  each  ($a) )  { 

echo  "$clave:  $valor\n"; 

} 


Este  ejemplo  mostrara:  20:  veinte  10:  diez  4:  cuatro  3:  tres 
Vea  tambien:  arsort  ),  asort)),  uasortj),  ksort)),  rsortQ,  y  sort'). 


usort  (PHP  3>=  3.0.3,  PHP  4  >=  4.0.0) 

Ordena  una  matriz  por  valores  mediante  una  funcion  definida  por  el  usuario 

void  usort  (array  matriz,  function  func_comparar ) 


Esta  funcion  ordenara  una  matriz  por  sus  valores  utilizando  una  funcion  suministrada  por  el  usuario.  Si  la 
matriz  que  desea  ordenar  necesita  utilizar  un  criterio  poco  trivial,  esta  es  la  funcion  que  debera  usar. 

La  funcion  de  comparacion  debera  devolver  un  entero  menor,  igual,  o  mayor  que  cero,  si  el  primer 
argumento  se  considera  respectivamente  menor  que,  igual  que,  o  mayor  que  el  segundo.  Si  dos  miembros 
resultan  ser  iguales,  su  orden  en  la  matriz  ordenada  sera  cualquiera. 

Ejemplo  1.  Ejemplo  de  usort() 

function  cmp  ($a,  $b)  { 

if  ($a  ==  $b)  return  0; 
return  ($a  >  $b)  ?  -1  :  1; 
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} 

$a  =  array  (3,  2,  5,  6,  1); 
usort  ($a,  cmp) ; 

while  (list  ($clave,  $valor)  =  each  ($a) )  { 

echo  "$clave:  $valor\n"; 

} 


Este  ejemplo  mostrara:  0:  6  1:  52:  33:  24:  1 

Nota:  Obviamente  en  este  caso  trivial  la  funcion  rsort;)  habria  sido  mas  apropiada. 


Aviso 

La  funcion  quicksort  subyacente  en  ciertas  librerias  de  C  (tales  como  las  de 
Solaris)  pueden  hacer  que  el  PHP  falle  si  la  funcion  de  comparacion  no  devuelve 
valores  consistentes. 


Vea  tambien:  arsort  ),  asort(),  ksortO,  rsort'')  y  sort)). 
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III.  Funciones  Ortograficas 

Las  funciones  aspell()  permiten  comprobar  la  ortografia  de  una  palabra  ofreciendote  sugerencias.  . 

Para  estas  funciones,  son  necesarias  las  librerias  aspell  (ortograficas)  disponibles  en 
http://metalab.unc.edu/kevina/aspell/ 
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aspell_new  (PHP  3>=  3.0.7,  PHP  4  >=  4.0.0) 

Lee  un  nuevo  diccionario 

int  aspell_new  (string  master,  string  personal) 

aspell_new()  Abre  un  nuevo  diccionario  devolviendo  el  identificador  de  este  para  ser  utilizado  en  otras 
funciones  ortograficas. 

Ejemplo  1.  Nuevo_diccionario 

$aspell_link=aspell_new ( "english" ) ; 


aspell_check  (PHP  3>=  3.0.7,  PHP  4  >=  4.0.0) 


Comprueba  una  palabra 


boolean  aspell_check  (int  dictionary_link ,  string  word) 


aspell_check()  comprueba  la  ortograffa  de  una  palabra,  y  devuelve  cierto(TRUE)  si  la  ortograffa  es 
correcta  .falso  (false)  si  no  lo  es  . 


Ejemplo  1.  aspell_check 

$aspell_link=aspell_new ( "english" ) ; 
if  (aspell_check ($aspell_link,  "testt" ) )  { 

echo  "Esta  bien  escrita"; 

}  else  { 

echo  "Lo  siento,  esta  mal  escrita"; 

} 


aspell_check-raw  (PHP  3>=  3.0.7,  PHP  4  >=  4.0.0) 


Comprueba  una  palabra  sin  cambiarla  o  intentar  arreglarla 
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boolean  aspell_check_raw  (int  dictionary_link ,  string  word) 


aspell_check_rawO  chequea  la  ortografia  de  una  palabra,sin  cambiarla  ni  intentar  arreglarla  este  bien  o 
mal.Si  esta  bien,  devuelve  cierto  (true),  si  no  lo  esta,  devuelve  falso(FALSE). 


Ejemplo  1.  aspell_check_raw 

$aspell_link=aspell_new ( "english" ) ; 
if  (aspell_check_raw ( $aspell_link,  "testt " ) )  { 

echo  "Esta  bein  escrito"; 

}  else  { 

echo  "Lo  siento,mal  escrito"; 

} 


aspell_suggest  (PHP  3>=  3.0.7,  PHP  4  >=  4.0.0) 

sugiere  la  ortografia  para  una  palabra 

array  aspell_suggest  (int  dictionary_link ,  string  word ) 


aspell_suggest()  devuelve  un  array  con  posibles  correciones  ortograficas  para  la  palabra  dada. 

Ejemplo  1.  aspell_suggest 

$aspell_link=aspell_new ( "english" ) ; 

if  (! aspell_check ( $aspell_link, "testt ") )  { 

$sugerencias=aspell_suggest ( $aspell_link, "testt") ; 

for($i=0;  $i  <  count ($sugerencias) ;  $i++)  { 

echo  "Posibles  palabras :  "  .  $sugerencias  [ $i ]  .  "<br>"; 

} 
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IV.  Funciones  matematicas  de  precision 
arbitraria 

Estas  funciones  solo  estan  disponibles  si  el  PHP  se  configuro  con  — enable-bcmath. 
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bcadd  (PHP3,  PHP  4  >=  4.0.0) 


Suma  dos  numeros  de  precision  arbitriaria. 


string  bcadd  (string  operando  izq, 


string  operando  der  [,  int  escala] ) 


Suma  el  operando  izq  con  el  operando  der  y  devuelve  la  suma  en  una  string.  El  parametro 
opcional  escala  se  usa  para  fijar  el  numero  de  dfgitos  tras  el  punto  decimal  que  apareceran  en  el 
resultado. 

Vea  tambien  bcsubj). 


bccomp  (PHP  3,  PHP  4  >=  4.0.0) 

Compara  dos  numeros  de  precision  arbitraria. 

int  bccomp  (string  operando  izq,  string  operando  der  [,  int  escala]) 


Compara  el  operando  izq  con  el  operando  der  y  devuelve  el  resultado  como  un  entero.  El 
parametro  opcional  escala  se  usa  para  fijar  el  numero  de  dfgitos  tras  el  punto  decimal  que  se  utilizaran 
en  la  comparacion.  El  valor  devuelto  es  0  si  los  dos  operandos  son  iguales.  Si  el  operando  izq  es 
mayor  que  el  operando  der  el  valor  devuelto  es  +1  y  si  el  operando  i  zq  es  menor  que  el 
operando  der  el  valor  devuelto  es  -1. 


bcdiv  (PHP  3,  PHP  4  >=  4.0.0) 


Divide  dos  numeros  de  precision  arbitraria. 


string  bcdiv  (string  operando  izq,  string  operando  der  [,  int  escala]) 

Divide  el  operando  izq  por  el  operando  der  y  devuelve  el  resultado.  El  parametro  opcional 
escala  fija  el  numero  de  dfgitos  tras  el  punto  decimal  a  usar  en  el  resultado. 

Vea  tambien  bcmulf  ). 
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bcmod  (PHP  3,  PHP  4  >=  4.0.0) 

Obtiene  el  modulo  de  un  numero  de  precision  arbitraria. 

string  bcmod  (string  operando  izq,  string  modulo) 

Obtiene  el  modulo  del  operando  izq  usando  modulo. 

Vea  tambien  bcdiv"). 

bcmul  (PHP  3,  PHP  4  >=4.0.0) 

Multiplica  dos  numeros  de  precision  arbitraria. 

string  bcmul  (string  operando  izq,  string  operando  der  [,  int  escala] ) 

Multiplica  el  operando  izq  por  el  operando  der  y  devuelve  el  resultado.  El  parametro  opcional 
escala  fij a  el  numero  de  dfgitos  tras  el  punto  decimal  del  resultado. 

Vea  tambien  bcdivl). 

bcpow  (PHP  3,  PHP  4  >=  4.0.0) 

Eleva  un  numero  de  precision  arbitraria  a  otro. 

string  bcpow  (string  x,  string  y  [,  int  escala ]) 

Eleva  x  a  la  potencia  de  y.  El  parametro  opcional  escala  se  puede  usar  para  fijar  el  numero  de  dfgitos 
tras  el  punto  decimal  del  resultado. 

Vea  tambien  bcsqrt)). 

bcscale  (PHP  3,  PHP  4  >=  4.0.0) 

Fija  el  parametro  de  escala  por  defecto  para  todas  las  funciones  matematicas  be. 

string  bcscale  (int  escala) 
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Esta  funcion  fija  el  parametro  de  escala  por  defecto  para  las  subsiguientes  funciones  matematicas  be  que 
no  especifican  dicho  parametro  explfcitamente. 


bcsqrt  (PHP3,  PHP  4  >=  4.0.0) 

Obtiene  la  rafz  cuadrada  de  un  numero  de  precision  arbitraria. 

string  bcsqrt  (string  operando,  int  escala) 

Devuelve  la  rafz  cuadrada  del  operando.  El  parametro  opcional  escala  fija  el  numero  de  dfgitos  tras 
el  punto  decimal  del  resultado. 

Vea  tambien  bepowj). 


besub  (PHP  3,  PHP  4  >=  4.0.0) 

Resta  un  numero  de  precision  arbitraria  de  otro. 

string  besub  (string  operando  izq,  string  operando  der  [,  int  escala]) 


Resta  el  operando  der  desde  el  operando  Izq  y  devuelve  el  resultado  en  una  cadena.  El 
parametro  opcional  escala  se  utiliza  para  fijar  el  numero  de  dfgitos  tras  el  punto  decimal  del  resultado. 

Vea  tambien  bcaddj). 
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V.  Bzip2  Compression  Functions 

This  module  uses  the  functions  of  the  bzip2  (http://sources.redhat.com/bzip2/)  library  by  Julian  Seward 
to  transparently  read  and  write  bzip2  (.bz2)  compressed  hies. 

Bzip2  support  in  PHP  is  not  enabled  by  default.  You  will  need  to  use  the  — with-bz2  configuration  option 
when  compiling  PHP  to  enable  bzip2  support.  This  module  requires  bzip2/libbzip2  version  >=  1 .0.x. 


Small  code  example 

This  example  opens  a  temporary  hie  and  writes  a  test  string  to  it,  then  prints  out  the  contents  of  the  hie. 

Ejemplo  1.  Small  bzip2  Example 

<?php 

$filename  =  " /tmp/test f ile . bz2 " ; 

$str  =  "This  is  a  test  string. \n"; 

//  open  file  for  writing 
$bz  =  bzopen ($filename,  "w"); 

/ /  write  string  to  file 
bzwrite($bz,  $str) ; 

/ /  close  file 
bzclose  ( $bz ) ; 

/ /  open  file  for  reading 
$bz  =  bzopen ($filename,  "r"); 

//  read  10  characters 
print  bzread($bz,  10); 

//  output  until  end  of  the  file  (or  the  next  1024  char)  and  close  it. 
print  bzread($bz); 

bzclose  ( $bz ) ; 

?> 
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bzclose  (PHP  4  >=  4.0.4) 


Close  a  bzip2  file  pointer 

int  bzclose  (int  bz) 


Closes  the  bzip2  file  referenced  by  the  pointer  bz. 

Returns  true  on  success  and  false  on  failure. 

The  file  pointer  must  be  valid,  and  must  point  to  a  file  successfully  opened  by  bzopen  '). 
See  also  bzopen). 


bzcompress  (php  4  >=  4  o  4) 


Compress  a  string  into  bzip2  encoded  data 


string  bzcompress  (string  source  [,  int  blocksize  [,  int  work factor] ] ) 


bzcompressO  compresses  the  source  string  and  returns  it  as  bzip2  encoded  data. 

The  optional  parameter  blocksize  specifies  the  blocksize  used  during  compression  and  should  be  a 
number  from  1  to  9  with  9  giving  the  best  compression,  but  using  more  resources  to  do  so.  blocksize 
defaults  to  4. 

The  optional  parameter  work  factor  controls  how  the  compression  phase  behaves  when  presented 
with  worst  case,  highly  repetitive,  input  data.  The  value  can  be  between  0  and  250  with  0  being  a  special 
case  and  30  being  the  default  value.  Regardless  of  the  work  factor,  the  generated  output  is  the  same. 


Ejemplo  1.  bzcompressO  Example 

<?php 

$str  =  "sample  data"; 

$bzstr  =  bzcompress ($str,  9) ; 
print  (  $bzstr  ) ; 

?> 


See  also  bzdecompressO- 


Bzip2 

bzdecompress  (php  4  >=  4  o  4) 


Decompresses  bzip2  encoded  data 


string  bzdecompress  (string  source  [,  int  small]) 


bzdecompress()  decompresses  the  source  string  containing  bzip2  encoded  data  and  returns  it.  If  the 
optional  parameter  small  is  true,  an  alternative  decompression  algorithm  will  be  used  which  uses  less 
memory  (the  maximum  memory  requirement  drops  to  around  2300K)  but  works  at  roughly  half  the 
speed.  See  the  bzip2  documentation  (http://sources.redhat.com/bzip2/)  for  more  information  about  this 
feature. 


Ejemplo  1.  bzdecompressO 

<?php 

$start_str  =  "This  is  not  an  honest  face?"; 
$bzstr  =  bzcompress ($start_str) ; 

print  (  "Compressed  String:  "  ); 
print  (  $bzstr  ) ; 
print  (  " \n<br>n"  ); 

$str  =  bzdecompress ($bzstr) ; 
print  (  "Decompressed  String:  "  ); 
print  (  $str  ) ; 
print  (  "\n<br>n"  ); 

?> 


See  also  bzcompress/). 

bzerrnO(PHP4>=4  0  4) 

Returns  a  bzip2  error  number 

int  bzerrno  (int  bz) 

Returns  the  error  number  of  any  bzip2  error  returned  by  the  file  pointer  bz. 
See  also  bzerror  )  and  bzerrstr 
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bzerror(PHP4>=4.o.4) 


Bzip2 


Returns  the  bzip2  error  number  and  error  string  in  an  array 

array  bzerror  (int  bz) 

Returns  the  error  number  and  error  string,  in  an  associative  array,  of  any  bzip2  error  returned  by  the  file 
pointer  bz. 

Ejemplo  1.  bzerror()  Example 

<?php 

$error  =  bzerror ( $bz ) ; 

echo  $error [ "errno" ] ; 
echo  $error [ "errstr " ] ; 

?> 

See  also  bzerrno ')  and  bzerrstr). 

bzerrstr(pHP4>=4  0  4) 

Returns  a  bzip2  error  string 

string  bzerrstr  (int  bz) 

Returns  the  error  string  of  any  bzip2  error  returned  by  the  file  pointer  bz. 

See  also  bzerrno ')  and  bzerror;)- 

bzflush  (PHP  4  >=  4.0.4) 

Force  a  write  of  all  buffered  data 

int  bzflush  (int  bz) 

Forces  a  write  of  all  buffered  bzip2  data  for  the  file  pointer  bz. 
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Returns  true  on  success,  false  on  failure. 
See  also  hzreatl ')  and  bz. write'). 


Bzip2 


bzopen  (PHP  4  >=  4.0.4) 

Open  a  bzip2  compressed  file 

int  bzopen  (string  filename ,  string  mode ) 


Opens  a  bzip2  (.bz2)  file  for  reading  or  writing,  filename  is  the  name  of  the  file  to  open,  mode  is 
similar  to  the  to  pen ')  function  (‘r’  for  read,  ‘w’  for  write,  etc.). 

If  the  open  fails,  the  function  returns  false,  otherwise  it  returns  a  pointer  to  the  newly  opened  file. 


Ejemplo  1.  bzopen()  Example 

<?php 

$bz  =  bzopen (" /tmp/foo . bz2 " ,  "r"); 

$decompressed_f ile  =  bzread($bz,  f ilesize (" /tmp/foo . bz2 ")) ; 
bzclose ( $bz ) ; 

print (  "The  contents  of  /tmp/foo. bz2  are:  "  ); 

print  (  " \n<br>n"  ); 

print  (  $decompressed_f ile  ) ; 

?> 


See  also  bzclose'). 


bzread  (PHP  4  >=4.0.4) 

Binary  safe  bzip2  file  read 

string  bzread  (int  bz  [,  int  length]) 


bzread()  reads  up  to  length  bytes  from  the  bzip2  file  pointer  referenced  by  bz.  Reading  stops  when 
length  (uncompressed)  bytes  have  been  read  or  EOF  is  reached,  whichever  comes  first.  If  the  optional 
parameter  length  is  not  specified,  bzreadQ  will  read  1024  (uncompressed)  bytes  at  a  time. 
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Ejemplo  1.  bzread()  Example 

<?php 

$bz  =  bzopen ( " /tmp/f oo . bz2 " ,  "r"); 

$str  =  bzread($bz,  2048); 
print (  $str  ) ; 

?> 


See  also  bzwrite')  and  bzopen  '). 


bzwrite  (PHP  4  >=  4.0.4) 

Binary  safe  bzip2  file  write 

int  bzwrite  (int  bz,  string  data  [,  int  length ]) 


bzwriteO  writes  the  contents  of  the  string  data  to  the  bzip2  file  stream  pointed  to  by  bz.  If  the  optional 
length  argument  is  given,  writing  will  stop  after  length  (uncompressed)  bytes  have  been  written  or  the 
end  of  string  is  reached,  whichever  comes  first. 


Ejemplo  1.  bzwriteO  Example 

<?php 

$str  =  "uncompressed  data"; 

$bz  =  bzopen (" /tmp/f oo . bz2 " ,  "w "); 
bzwrite  ($bz,  $str,  strlen ($str) ) ; 
bzclose  ( $bz ) ; 

?> 


See  also  bzread))  and  bzopen)). 


VI.  Funciones  de  calendario 


Las  funciones  de  calendario  solo  estan  disponibles  si  ha  compilado  la  extension  de  calendario  que  hay  en 
dl/calendar.  Lea  el  documento  dl/README  como  referenda  de  uso. 

La  extension  calendar  presenta  una  serie  de  funciones  para  simplificar  la  conversion  entre  los  distintos 
formatos  de  calendario.  El  intermediario  estandar  en  que  se  basa  es  en  la  Cuenta  de  Dias  Juliana.  La 
Cuenta  de  Dias  Juliana  es  una  cuenta  que  comienza  mucho  antes  que  lo  que  mucha  gente  podrfa 
necesitar  contar  (como  alrededor  del  4000  AC).  Para  convertir  entre  sistemas  de  calendario,  primero 
debera  convertir  a  la  Cuenta  de  Dias  Juliana  y  luego  al  sistema  de  su  eleccion.  jLa  Cuenta  de  Dias  es 
muy  diferente  del  Calendario  Juliano!  Para  mas  informacion  sobre  sistemas  de  calendario,  visite 
http://genealogy.org/~scottlee/cal-overview.html.  En  estas  instrucciones  se  han  inclufdo  extractos 
entrecomillados  de  dicha  pagina. 
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JDToGregorian  (PHP  3,  PHP  4  >=  4.0.0) 

Convierte  de  Cuenta  de  Dias  a  fecha  Gregoriana 

string  jdtogregorian  (int  diajuliano) 


Convierte  de  Cuenta  de  Dias  Juliana  a  una  cadena  que  contiene  la  fecha  Gregoriana  en  formato 
"mes/dfa/ano" 


GregorianToJD  (PHP  3,  PHP  4  >=  4.0.0) 


Convierte  de  fecha  Gregoriana  a  Cuenta  de  Dias 


int  gregorianto jd  (int  mes,  int  dia,  int  anno ) 


El  rango  valido  para  el  Calendario  Gregoriano  es  desde  el  4714  A.C.  hasta  el  9999  D.C. 

Aunque  este  programa  puede  manejar  fechas  tan  lejanas  como  el  4714  A.C.,  usarlo  no  tendrfa  sentido.  El 
calendario  Gregoriano  fue  institufdo  el  15  de  octubre  de  1582  (o  el  5  de  octubre  de  1582  en  el  calendario 
Juliano).  Algunos  pafses  no  lo  aceptaron  hasta  mucho  despues.  Por  ejemplo.  Gran  Bretana  se  convirtio 
en  1752,  la  URSS  en  1918  y  Grecia  en  1923.  Muchos  pafses  europeos  usaron  el  calendario  Juliano  antes 
que  el  Gregoriano. 

Ejemplo  1.  Funciones  de  calendario 

<?php 

$jd  =  GregorianTo JD ( 10 , 11 , 1 97 0 ) ; 
echo ( " $  jd\n" ) ; 

$gregoriano  =  JDToGregorian ( $ jd) ; 
echo ( " $gregoriano\n" ) ; 

?> 


JDToJulian  (PHP  3,  PHP  4  >=  4.0.0) 

Convierte  de  Cuenta  de  Dfas  a  Calendario  Juliano 

string  jdtojulian  (int  diajuliano) 


181 


Calendario 


Convierte  una  Cuenta  de  Dias  Juliana  a  una  cadena  que  contiene  la  fecha  del  Calendario  Juliano  en 
formato  "mes/dia/ano". 


JulianToJD  (PHP  3,  PHP  4  >=  4.0.0) 

Convierte  de  Calendario  Juliano  a  Cuenta  de  Dias 

int  juliantojd  (int  mes,  int  dia,  int  anno) 


Rango  valido  para  el  Calendario  Juliano:  del  4713  A.C  al  9999  D.C. 

Aunque  este  programa  puede  manejar  fechas  tan  lejanas  como  el  4713  A.C.,  usarlo  no  tendrfa  sentido.  El 
calendario  se  creo  en  el  46  A.C.,  pero  sus  detalles  no  se  estabilizaron  hasta  al  menos  el  8  D.C.,  y  quizas 
no  lo  hiciera  hasta  el  siglo  IV.  Ademas,  el  comienzo  de  un  ano  variaba  de  una  a  otra  cultura:  no  todas 
aceptaban  enero  como  el  primer  mes. 


JDToJewish  (PHP  3,  PHP  4  >=4.0.0) 

Convierte  de  Cuenta  de  Dias  a  Calendario  Judio 

string  jdtojewish  (int  dia juliano) 


Convierte  una  Cuenta  de  Dias  Juliana  al  Calendario  Judio. 


JewishToJD  (PHP  3,  PHP  4  >=4.0.0) 

Convierte  del  Calendario  Judio  a  la  Cuenta  de  Dias 

int  jewishtojd  (int  mes,  int  dia,  int  anno) 


El  rango  valido  para  el  Calendario  Judio  va  del  ano  1  hasta  el  9999 

Aunque  este  programa  puede  manejar  fechas  tan  lejanas  como  el  ano  1  (3761  A.C.),  usarlo  no  tendrfa 
sentido.  El  Calendario  Judio  ha  estado  en  uso  miles  de  anos,  pero  en  los  dias  primeros  no  habia  una 
formula  que  calculara  el  comienzo  de  un  mes.  Un  mes  comenzaba  cuando  se  veia  por  primera  vez  la  luna 
nueva. 
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JDToFrench  (PHP  3,  PHP  4  >=  4.0.0) 

Convierte  de  Cuenta  de  Dias  al  Calendario  Republicano  Frances 

string  jdtofrench  (int  diajuliano) 


Convierte  una  Cuenta  de  Dias  Juliana  al  Calendario  Republicano  Frances. 


FrenchToJD  (PHP  3,  PHP  4  >=  4.0.0) 

Convierte  del  Calendario  Republicano  Frances  a  la  Cuenta  de  Dias 

int  frenchtojd  (int  mes,  int  dia,  int  anno) 


Convierte  una  fecha  del  Calendario  Republicano  Frances  a  la  Cuenta  de  Dias  Juliana. 

Estas  rutinas  solo  convierten  fechas  entre  los  anos  1  y  14  (fechas  Gregorianas  del  22  de  septiembre  de 
1792  al  22  de  septiembre  de  1806).  Esto  cubre  ampliamente  el  periodo  en  el  que  estuvo  en  uso  este 
calendario. 


JDMonthName  (PHP  3,  PHP  4  >=  4.0.0) 

Devuelve  el  nombre  de  un  mes 


string  jdmonthname  (int  diajuliano,  int  modo) 


Devuelve  una  cadena  que  contiene  el  nombre  del  mes.  modo  le  dice  a  esta  funcion  a  que  calendario  debe 
convertir  la  Cuenta  de  Dias  Juliana,  y  que  tipo  de  nombres  de  mes  debe  devolver. 

Tabla  1.  Modos  de  calendario 


Modo 

Significado 

0 

Gregoriano  -  abreviado 

1 

Gregoriano 

2 

Juliano  -  abreviado 

3 

Juliano 

4 

Judfo 
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Modo 

Significado 

5 

Republicano  Frances 

JD  Day  Of  Week  (PHP  3,  PHP  4  >=  4.0.0) 

Devuelve  el  dfa  de  la  semana 


mixed  jddayofweek  (int  diajuliano,  int  modo) 


Devuelve  el  dfa  de  la  semana.  Dependiendo  del  modo,  devuelve  un  entero  o  una  cadena. 


Tabla  1.  Modos  para  el  dfa  de  la  semana 


Modo 

Significado 

0 

devuelve  el  dfa  de  la  semana  como  entero 
(0=domingo,  l=lunes,  etc) 

1 

devuelve  una  cadena  con  el  dfa  de  la  semana  (ingles, 
gregoriano) 

2 

devuelve  una  cadena  con  el  dfa  de  la  semana 
abreviado  (ingles,  gregoriano) 

easter_date  (PHP  3>=  3.0.9,  PHP  4  >=  4.0.0) 

devuelve  la  marca  de  tiempo  UNIX  para  la  medianoche  de  Pascua  de  un  ano  dado 

int  easter_date  (int  anno) 


Devuelve  la  marca  de  tiempo  UNIX  que  corresponde  a  la  medianoche  de  Pascua  del  ano  dado.  Si  no  se 
especifica  un  ano,  se  asume  el  actual. 

Aviso:  Esta  funcion  generara  un  aviso  si  el  ano  esta  fuera  del  rango  para  las  marcas  de  tiempo  del  UNIX 
(es  decir,  antes  de  1970  o  despues  del  2037). 

Ejemplo  1.  ejemplo  de  easter_date() 

echo  date  (  "d-M-Y",  easter_date ( 1 999)  );  /*  "04-Apr-1999"  */ 

echo  date (  "d-M-Y",  easter_date (2000)  );  /*  "23-Apr-2000"  */ 
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echo  date (  "d-M-Y",  easter_date (2001)  ); 


/*  "15-Apr-2001"  */ 


La  fecha  del  Dia  de  Pascua  fue  definida  por  el  Concilio  de  Nicea  en  el  325  D.C.  como  el  domingo  tras  la 
primera  luna  llena  que  cayera  en  o  despues  del  equinoccio  de  Primavera.  El  equinoccio  se  supone  que 
siempre  cae  en  el  21  de  marzo,  de  modo  que  el  calculo  se  reduce  a  determinar  la  fecha  de  la  luna  llena  y 
la  del  domingo  siguiente.  El  algoritmo  usado  aqui  fue  introducido  en  el  ano  532  por  Dionisio  Exiguo. 
Bajo  el  Calendario  Juliano  (para  anos  anteriores  al  1753),  se  usa  un  ciclo  simple  de  19  anos  para  calcular 
las  fases  de  la  luna.  Bajo  el  Calendario  Gregoriano  (anos  posteriores  al  1753,  disenado  por  Clavio  y 
Lilio,  e  introducido  por  el  Papa  Gregorio  XIII  en  Octubre  de  1582,  y  en  Gran  Bretana  y  sus  colonias  en 
septiembre  de  1752)  se  anaden  dos  factores  de  correccion  para  hacer  el  ciclo  mas  preciso. 

(El  codigo  se  basa  en  un  programa  en  C  de  Simon  Kershaw,  <webmaster@ely.anglican.org>) 

Vea  easter_days ')  para  calcular  la  Pascua  antes  del  1970  o  despues  del  2037. 


easter_days  (PHP  3>=  3.0.9,  PHP  4  >=  4.0.0) 

obtiene  el  numero  de  dias  tras  el  21  de  marzo  en  que  cae  la  Pascua  en  un  ano  dado 

int  easter_days  (int  anno) 


Devuelve  el  numero  de  dias  tras  el  21  de  marzo  en  que  cae  la  Pascua  en  un  ano  dado.  Si  no  se  especifica 
ano,  se  asume  el  actual. 

Esta  funcion  se  puede  usar  en  lugar  de  easter_date  j  para  calcular  la  Pascua  para  anos  que  se  salen  del 
rango  de  las  marcas  de  fecha  del  UNIX  (o  sea,  antes  del  1970  o  despues  del  2037). 


Ejemplo  1.  ejemplo  de  easter  date  ) 


echo 

easter_days (1999)  ; 

/* 

14, 

es 

decir , 

4 

de 

abril 

*/ 

echo 

easter_days (1492)  ; 

/* 

32, 

es 

decir , 

22 

de 

abril 

★ 

echo 

easter_days (1913) ; 

/* 

2, 

es 

decir, 

23 

de 

marzo 

*/ 

La  fecha  del  Dia  de  Pascua  fue  definida  por  el  Concilio  de  Nicea  en  el  325  D.C.  como  el  domingo  tras  la 
primera  luna  llena  que  cayera  en  o  despues  del  equinoccio  de  Primavera.  El  equinoccio  se  supone  que 
siempre  cae  en  el  21  de  marzo,  de  modo  que  el  calculo  se  reduce  a  determinar  la  fecha  de  la  luna  llena  y 
la  del  domingo  siguiente.  El  algoritmo  usado  aqui  fue  introducido  en  el  ano  532  por  Dionisio  Exiguo. 
Bajo  el  Calendario  Juliano  (para  anos  anteriores  al  1753),  se  usa  un  ciclo  simple  de  19  anos  para  calcular 
las  fases  de  la  luna.  Bajo  el  Calendario  Gregoriano  (anos  posteriores  al  1753,  disenado  por  Clavio  y 
Lilio,  e  introducido  por  el  Papa  Gregorio  XIII  en  Octubre  de  1582,  y  en  Gran  Bretana  y  sus  colonias  en 
septiembre  de  1752)  se  anaden  dos  factores  de  correccion  para  hacer  el  ciclo  mas  preciso. 

(El  codigo  se  basa  en  un  programa  en  C  de  Simon  Kershaw,  <webmaster@ely.anglican.org>) 

Vea  tambien  easter_date(). 
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VII.  CCVS  API  Functions 


These  functions  interface  the  CCVS  API,  allowing  you  to  directly  work  with  CCVS  from  your  PHP 
scripts.  CCVS  is  RedHat’s  (http://www.redhat.com/)  solution  to  the  "middle-man"  in  credit  card 
processing.  It  lets  you  directly  address  the  credit  card  clearing  houses  via  your  *nix  box  and  a  modem. 
Using  the  CCVS  module  for  PHP,  you  can  process  credit  cards  directly  through  CCVS  via  your  PHP 
Scripts.  The  following  references  will  outline  the  process. 

To  enable  CCVS  Support  in  PHP,  hist  verify  your  CCVS  installation  directory.  You  will  then  need  to 
configure  PHP  with  the  — with-ccvs  option.  If  you  use  this  option  without  specifying  the  path  to  your 
CCVS  installation,  PHP  Will  attempt  to  look  in  the  default  CCVS  Install  location  (/usr/local/ccvs).  If 
CCVS  is  in  a  non-standard  location,  run  configure  with:  — with-ccvs=$ccvs_path,  where 
$ccvs_path  is  the  path  to  your  CCVS  installation.  Please  note  that  CCVS  support  requires  that 
$ccvs_path/lib  and  $ccvs_path/include  exist,  and  include  cv_api.h  under  the  include  directory  and 
libccvs.a  under  the  lib  directory. 

Additionally,  a  ccvsd  process  will  need  to  be  running  for  the  configurations  you  intend  to  use  in  your 
PHP  scripts.  You  will  also  need  to  make  sure  the  PHP  Processes  are  running  under  the  same  user  as  your 
CCVS  was  installed  as  (e.g.  if  you  installed  CCVS  as  user  ’ccvs’,  your  PHP  processes  must  run  as  ’ccvs’ 
as  well.) 

Additional  information  about  CCVS  can  be  found  at  http://www.redhat.com/products/ccvs. 

This  documentation  section  is  being  worked  on.  Until  then,  RedHat  maintains  slightly  outdated  but  still 
useful  documentation  at  http://www.redhat.com/products/ccvs/support/CCVS3.3docs/ProgPHP.html. 
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(unknown) 


0 
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VIII.  soporte  de  las  funciones  COM  para 
Windows 

Estas  funciones  solo  estan  disponibles  en  la  version  para  Windows  de  PHP.  Estas  funciones  han  sido 
anadidas  en  PHP4. 
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comjoad  (PHP3>=  3.0.3) 

??? 


string  com_load  (string  module  name,  string  [server  name]) 


com_invoke  (php  3>=  3.0.3) 

??? 

mixed  com_invoke  (resource  object,  string  function_name ,  mixed  [function 
parameters,  ...]) 


com_propget  (PHP  3>=  3.0.3,  PHP  4  >=  4.0.0) 

??? 

mixed  com_propget  (resource  object,  string  property ) 


com_get  (PHP  3>=  3.0.3,  PHP  4  >=  4.0.0) 

??? 


mixed  com_get  (resource  object,  string  property) 


com_propput  (PHP  3>=  3.0.3,  PHP  4  >=  4.0.0) 

??? 
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void  com_propput  (resource  object,  string  property ,  mixed  value) 


com_propset  (PHP  3>=  3.0.3,  PHP  4  >=  4.0.0) 

??? 


void  com_propset  (resource  object,  string  property ,  mixed  value) 


Esta  funcion  es  un  alias  para  com_propputO- 


com_set  (PHP  3>=  3.0.3,  PHP  4  >=  4.0.0) 

??? 


void  com_set  (resource  object,  string  property ,  mixed  value) 


Esta  funcion  es  un  alias  para  com_set(). 
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IX.  Funciones  de  Clases/Objectos 
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get_class_methods  (php  4  >=  4.0.0 

Devuelve  un  vector  (matriz  unidimensional)  con  los  nombres  de  los  metodos  de  la  clase  en  question. 

vector  get_class_methods  (string  class_name) 

Esta  funcion  devuelve  un  vector  con  los  nombres  de  los  metodos  definidos  en  la  clase  especificada  como 

class_name. 


get_class_vars  (php  4  >=  4 .0 .0 

Devuelve  un  vector  con  las  propiedades  (inicializadas  por  defecto)  de  la  clase 

array  get_class_vars  (string  class_name) 

Esta  funcion  devuelve  un  vector  con  las  propiedades  que  han  sido  inicializadas  por  defecto  en  la  clase. 


get_object_vars  php  4  >=  4  0  0 

Devuelve  un  vector  de  propiedades  del  objecto 

array  get_class_vars  (object  obj) 

Esta  funcion  devuelve  un  vector  con  las  propiedades  de  objecto  definidas  en  el  objecto  especificado 
como  obj. 


method_exists  <php  4  >=  4  0  o> 

Comprueba  que  el  metodo  de  clase  existe 

bool  method_exists  (object  object,  string  method_name ) 

Esta  funcion  devuelve  verdadero  si  el  metodo  referido  por  method_name  ha  sido  definido  en  el  objecto 
object ,  en  cualquier  otro  case  devuelve  falso 
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X.  Funciones  de  ClibPDF 


ClibPDF  Le  permite  crear  documentos  PDF  con  PHP.  Esta  disponible  en  FastIO  (http://www.fastio.com) 
pero  no  es  software  libre.  Deberfa  leer  la  licencia  antes  de  comenzar  a  utilizar  ClibPDF.  Si  usted  no 
puede  cumplir  el  acuerdo  de  la  licencia  considere  el  utilizar  la  pdflib  de  Thomas  Merz,  que  tambien  es 
muy  potente.  La  funcionalidad  y  la  API  de  ClibPDF  son  similares  a  la  pdflib  de  Thomas  Merz  pero,  de 
acuerdo  con  FastIO,  ClibPDF  es  mas  rapida  y  crea  documentos  mas  pequenos.  Esto  puede  haber 
cambiado  con  la  nueva  version  2.0  de  pdflib.  Un  simple  banco  de  pruebas  (el  ejemplo  pdfclock.c  de 
pdflib  2.0  trasformado  en  un  script  php)  en  realidad  no  muestra  ninguna  diferencia  en  velocidad.  Por 
tanto,  pruebe  las  dos  y  vea  cual  hace  el  mejor  trabajo  para  usted. 

Esta  documentation  deberfa  ser  lefda  junto  con  el  manual  de  ClibPDF  ya  que  este  explica  la  librerfa  con 
mucho  mas  detalle. 

Muchas  funciones  en  le  ClibPDF  nativa  y  el  modulo  PHP,  asf  como  en  pdflib,  tienen  el  mismo  nombre. 
Todas  las  funciones  excepto  cpdf_open()  toman  el  manejador  del  documento  com  el  primer  parametro. 
Actualmente  este  manejador  no  se  usa  internamente  desde  que  ClibPDF  no  soporta  la  creation  de  varios 
documentos  PDF  al  mismo  tiempo.  Realmente,  ni  deberfa  intentarlo,  los  resultados  son  impredecibles. 
No  puedo  supervisar  cuales  son  las  consecuencias  en  un  sistema  multihilo.  De  acuerdo  con  el  autor  de 
ClibPDF,  esto  cambiara  en  alguno  de  las  proximas  veriones  (la  version  actual,  cuando  eto  fue  escrito  es 
1.10).  Si  usted  necesita  esta  capacidad,  use  el  modulo  pdflib. 

Nota:  La  funcion  cpdf_set_font;)  ha  cambiado  desde  que  PHP3  soporta  fuentes  asiaticas.  El 
parametro  que  codifica  ya  no  es  un  entero  sino  una  cadena. 


Una  gran  ventaja  de  ClibPDF  sobre  pdflib  es  la  posibilidad  de  crear  el  documento  PDF  completamente 
en  memoria  sin  usar  ficheros  temporales.  Esto  tambien  proporciona  la  capaciad  de  pasar  coordenadas  en 
una  unidad  de  longitud  predefinida.  Esta  es  una  cualidad  util  pero  puede  ser  simulada  con  pdf  translate  ). 

La  mayorfa  de  las  funciones  son  faciles  de  usar.  La  parte  mas  diffcil  es,  probablemente,  crear  un 
documento  PDF  muy  simple.  El  siguiente  ejemplo  deberfa  ayudarle  a  comenzar.  En  el  se  crea  un 
documento  con  una  pagina.  La  pagina  contiene  el  texto  "Times-Roman"  con  una  fuente  de  30pt.  El  texto 
esta  subrayado. 

Ejemplo  1.  Ejemplo  simple  de  ClibPDF 


<?php 

$cpdf  =  cpdf_open ( 0 ) ; 

cpdf_page_init ($cpdf,  1,  0,  595,  842); 
cpdf_add_outline ($cpdf ,  0,  0,  0,  1,  "Page  1"); 
cpdf_set_f ont ( $cpdf ,  "Times-Roman",  30,  "WinAnsiEncoding" ) ; 
cpdf_set_text_rendering ( $cpdf ,  1) ; 

cpdf_text ( $cpdf ,  "Times  Roman  outlined",  50,  750); 

cpdf_moveto ( $cpdf ,  50,  740); 

cpdf_lineto ( $cpdf ,  330,  740); 

cpdf_stroke ($cpdf ) ; 

cpdf_f inalize ($cpdf) ; 

Header ( "Content -type :  application/pdf " ) ; 
cpdf_output_buf f er ( $cpdf )  ; 
cpdf_close ($cpdf )  ; 
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?> 

La  distribution  de  pdflib  contiene  un  ejemplo  mas  comlejo  que  crea  una  serie  de  paginas  con  un  reloj 
analogico.  Aquf  esta  ese  ejemplo  convertido  en  PHP  usando  la  extension  ClibPDF: 

Ejemplo  2.  Ejemplo  con  pdfclock  de  la  distribution  pdflib  2.0 

<?php 

$radius  =  200; 

$margin  =  20; 

$pagecount  =  40; 

$pdf  =  cpdf_open ( 0 )  ; 

cpdf_set_creator ($pdf ,  "pdf_clock . php3 " ) ; 
cpdf_set_title ($pdf ,  "Reloj  Analogico"); 

while ( $pagecount--  >  0)  { 

cpdf_page_init ( $pdf ,  $pagecount+l ,  0,  2  *  ($radius  +  $margin) ,  2  *  ($radius  +  $mar- 
gin) ,  1.0); 

cpdf_set_page_animation ( $pdf ,  4,  0.5,  0,  0,  0);  /*  limpiar  */ 

cpdf_translate ($pdf ,  $radius  +  $margin,  $radius  +  $margin) ; 
cpdf_save ($pdf ) ; 

cpdf_setrgbcolor ( $pdf ,  0.0,  0.0,  1.0); 

/*  cambio  de  minuto  */ 

cpdf_setlinewidth ( $pdf ,  2.0); 

for  ($alpha  =  0;  $alpha  <  360;  $alpha  +=  6) 

{ 

cpdf_rotate ( $pdf ,  6.0); 
cpdf_moveto ( $pdf ,  $radius,  0.0); 
cpdf_lineto ( $pdf ,  $radius-$margin/3 ,  0.0); 
cpdf_stroke ($pdf )  ; 

} 

cpdf_restore ($pdf ) ; 
cpdf_save ($pdf )  ; 

/*  cambios  de  5  minutos  */ 

cpdf_setlinewidth ( $pdf ,  3.0); 

for  ($alpha  =  0;  $alpha  <  360;  $alpha  +=  30) 

{ 

cpdf_rotate ( $pdf ,  30.0); 
cpdf_moveto ( $pdf ,  $radius,  0.0); 
cpdf_lineto ( $pdf ,  $radius-$margin,  0.0); 
cpdf_stroke ($pdf )  ; 

} 

$ltime  =  getdateO; 

/*  dibujar  la  aguja  de  las  horas  */ 
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cpdf_save ($pdf )  ; 

cpdf_rotate ( $pdf ,  - ( ( $ltime [ ' minutos' ] / 60 . 0 )  +  $ltime [ ' horas'  ]  -  3.0)  *  30.0) 

cpdf_moveto ( $pdf ,  -$radius/10,  -$radius/20)  ; 

cpdf_lineto ( $pdf ,  $radius/2,  0.0); 

cpdf_lineto ( $pdf ,  -$radius/10,  $radius/20); 

cpdf_closepath ($pdf ) ; 

cpdf_fill ($pdf ) ; 

cpdf_restore ($pdf ) ; 

/*  dibujar  el  minutero  */ 
cpdf_save ($pdf ) ; 

cpdf_rotate ( $pdf ,  - ( ( $ltime [ ' segundos ' ] / 60 . 0 )  +  $ltime [' minutos' ]  -  15.0)  *  6 

cpdf_moveto ( $pdf ,  -$radius/10,  -$radius/20 ) ; 

cpdf_lineto ( $pdf ,  $radius  *  0.8,  0.0); 

cpdf_lineto ( $pdf ,  -$radius/10,  $radius/20); 

cpdf_closepath ($pdf )  ; 

cpdf_fill ($pdf )  ; 

cpdf_restore ($pdf )  ; 

/*  dibujar  la  seguna  mano  */ 
cpdf_setrgbcolor ( $pdf ,  1.0,  0.0,  0.0); 
cpdf_setlinewidth ($pdf ,  2) ; 
cpdf_save ($pdf )  ; 

cpdf_rotate ( $pdf ,  -(( $ltime [' segundos ' ]  -  15.0)  *  6.0)); 

cpdf_moveto ( $pdf ,  -$radius/5,  0.0); 

cpdf_lineto ( $pdf ,  $radius,  0.0); 

cpdf_stroke ($pdf)  ; 

cpdf_restore ($pdf )  ; 

/*  dibujar  un  pequeno  circulo  en  el  centro  */ 
cpdf_circle ( $pdf ,  0,  0,  $radius/30); 
cpdf_fill ($pdf )  ; 

cpdf_restore ($pdf )  ; 

cpdf_f inalize_page ( $pdf ,  $pagecount  +  l ) ; 

} 

cpdf_f inalize ( $pdf ) ; 

Header ( "Content-type :  application/pdf " ) ; 
cpdf_output_buf fer ($pdf ) ; 
cpdf_close ($pdf) ; 

?> 


195 


ClibPDF 


cpdf_global_set_document  Jimits  (php  4  >=  4.0.0 


Sets  document  limits  for  any  pdf  document 


void  cpdf_global_set_document_limits  (int  maxpages ,  int  maxfonts,  int 
maximages ,  int  maxannotations ,  int  maxobjects) 


La  funcion  cpdf_global_set_document_limits()  define  varios  limites  del  documento.  Esta  funcion  debe 
ser  llamada  antes  de  cpdf_open ')  para  que  haga  efecto.  Elio  define  los  limites  de  cualquier  documento 
abierto  con  anterioridad. 

Vea  tambien  cpdf_open  ). 


cpdf_set_creator  (PHP  3>=  3.0.8,  PHP  4  >=  4.0.0) 

Define  el  campo  creator  en  el  documento  PDF 

void  cpdf_set_creator  (string  creator) 

La  funcion  cpdf_set_creator()  define  el  creador  de  un  documento  PDF. 
Vea  tambien  cpdf_set_subject(),  cpdf_set_title '),  cpdf_set_keywords(). 


cpdf_set_title  (PHP  3>=  3.0.8,  PHP  4  >=  4.0.0) 

Define  el  campo  title  de  un  documento  PDF 

void  cpdf_set_title  (string  title) 

La  funcion  cpdf_set_title()  define  el  tftulo  de  un  documento  PDF 

Vea  tambien  cpdf_set_subject(),  cpdf_set_creator(),  cpdf_set_kcy  woitls  ). 


cpdf_set_subject  (PHP  3>=  3.0.8,  PHP  4  >=  4.0.0) 


Define  el  valor  del  campo  subjet  de  un  documento  PDF 
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void  cpdf_set_sub ject  (string  subject ) 

La  funcion  cpdf_set_subject()  define  el  asunto  de  un  documento  PDF 
Vea  tambien  cpdf  set  ti tie  ( J,  cpdf_set_creatoi\),  cpdf_set_keywords(). 


cpdf_set_keywords  (php  3>=  3.0.8,  php  4  >=  4.o.o) 

Pone  el  valor  del  campo  ’keywords’ (palabras  clave)  de  un  documento  PDF 

void  cpdf_set_keywords  (string  keywords) 

La  funcion  cpdf_set_keywords()  define  las  palabras  clave  de  un  documento  PDF. 
Vea  tambien  cpdf_set_titleO,  cpdf_set_creator'),  cpdf_set_subject '). 


cpdf_open  (PHP  3>=  3.0.8,  PHP  4  >=  4.0.0) 
Abre  un  nuevo  documento  PDF 


int  cpdf_open  (int  compression,  string  filename) 


LA  funcion  cpdf_open()  abre  un  documento  PDF  nuevo.  El  primer  parametro  activa  la  compresion  del 
documento  si  no  es  igual  a  0.  El  segundo  parametro,  opcional,  es  el  fichero  en  el  que  el  documento  es 
escrito.  Si  es  omitido,  el  documento  es  creado  en  memoria  y  puede  ser  escrito  en  un  fichero  mediante  la 
funcion  cpdf_save_to_fi  le ')  o  escrito  por  la  salida  estandar  con  cpdf_output_buffer(). 

Nota:  El  valor  de  retorno  sera  necesario  en  nuevas  versiones  de  ClibPDF  como  el  primer  parametro 
en  todas  las  demas  funciones  que  escriben  en  el  documento  PDF. 

La  librena  ClibPDF  toma  el  nombre  de  fichero  como  sinonimo  de  stdout  (salida  estandar).  Si  se 
compila  PHP  como  modulo  de  apache  esto  no  funcionara  porque  la  manera  en  que  ClibPDF 
direcciona  a  la  salida  estandar  no  funciona  con  apache.  Listed  puede  solucionar  este  problema 
evitando  el  enobre  de  fichero  y  usando  cpdf_output_buffer;)  para  la  salida  de  documentos  PDF. 


Vea  tambien  cpdf_closeO,  cpdf_output_buffer{). 
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Cierra  un  documento  PDF 


void  cpdf_close  (int  pdf  document) 


La  funcion  cpdf_close()  cierra  un  documento  PDF.  Esta  deberfa  ser  la  ultima  operation  incluso  despues 
de  cpdf_finalize(),  cpdf_output_buffer ')  y  cpdt’_save_to_fi  le). 

Vea  tambien  cpdfopcn '). 


cpdf_page_init  (PHP  3>=  3.0.8,  PHP  4  >=  4.0.0) 


Comienza  una  nueva  pagina 


void  cpdf_page_init  (int  pdf  document ,  int  page  number, 
double  height,  double  width,  double  unit ) 


int  orientation , 


La  funcion  cpdf_page_init()  crea  una  nueva  pagina  de  altura  height  y  profundidad  width.  La  pagina 
tiene  el  numero  pa ge  n umber  y  orientation  ori entati on.  ori entation  puede  ser  0  para 
retrato  y  1  para  paisaje.  El  ultimo  parametro  opcional  unit  define  la  unidad  del  sistema  de  coordenadas. 
El  valor  deberfa  ser  el  numero  de  puntos  postscript  por  unidad.  Como  el  valor  de  una  pulgada  el  igual  a 
72  puntos,  un  valor  de  72  serfa  la  unidad  para  una  pulgada.  Por  defecto  es  72. 

Vea  tambien  cpdf_set_current_pageO- 


cpdf_finalize_page  (PHP  3>=  3.0.10,  PHP  4  >=  4.0.0) 


Finaliza  una  pagina 


void  cpdf  finalize  page  (int  pdf  document,  int  page  number) 


La  funcion  cpdf_finalize_page()  finaliza  una  pagina  con  numero  de  pagina  page  number.  Esta 
funcion  es  solo  para  ahorrar  memoria.  Una  pagina  terminada  ocupa  menos  memoria  pero  no  puede 
volver  a  ser  modificada. 

Vea  tambien  cpdf_page_init(). 
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ClibPDF 


Finaliza  un  documento 

void  cpdf_f inalize  (int  pdf  document ) 

La  funcion  cpdf_finalize()  finaliza  un  documento.  Alin  se  tiene  que  llamar  a  cpdf_closeO. 

Vea  tambien  cpdf_close(). 

cpdf_output_buffer  (php  3>=  3.0.9,  php  4  >=  4.0.0) 

Pone  el  documento  PDF  en  el  buffer  de  memoria 

void  cpdf_output_buf fer  (int  pdf  document) 

La  funcion  cpdf_output_buffer()  muestra  el  documento  PDF  por  la  salida  estandar.  El  documento  debe 
ser  creado  en  memoria,  que  es  el  caso  de  la  funcion  cpdf_open()  cuando  ha  sido  llamada  sin  parametros. 

Vea  tambien  cpdf_open)). 

cpdf_save_to_file  (PHP  3>=  3.0.8,  PHP  4  >=  4.0.0) 

Escribe  el  documento  PDF  en  un  fichero 

void  cpdf_save_to_f ile  (int  pdf  document ,  string  filename) 

La  funcion  cpdf_  _save_to_file()  guarda  el  documento  PDF  en  un  fichero  si  este  documeto  ha  sido  creado 
en  memoria.  Esta  funcion  no  es  necesaria  si  el  documento  PDF  ha  sido  abierto  mediante  la 
especificacion  de  un  nombre  de  fichero  en  la  funcion  cpdf_open')- 

Vea  tambien  cpdf_output_bu f fc r ' ) ,  cpdf_openO- 

cpdf_set_current_page  php  3>=  3.0.9,  php  4  >=  4  0 0 

Define  la  pagina  actual 
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void  cpdf_set_current_page  (int  pdf  document ,  int  page  number ) 


La  funcion  cpdf_set_current_page()  define  la  pagina  en  la  que  se  van  a  realizar  todas  las  operaciones. 
Uno  puede  cambiar  entre  paginas  a  menos  que  una  pagina  ha  sido  finalizada  con  cpdf_finalize_pageO- 

Vea  tambien  cpdf  biialize  page'j. 


cpdf_begin_text  (PHP  3>=  3.0.8,  PHP  4  >=  4.0.0) 


Inicializa  una  seccion  de  texto 


void  cpdf_begin_text  (int  pdf  document ) 


La  funcion  cpdf_begin_text()  comienza  una  seccion  de  texto.  Debe  ser  terminada  con  cpdf_end_text\). 
Ejemplo  1.  Salida  de  texto 

<?php  cpdf_begin_text ($pdf )  ; 

cpdf_set_f ont ( $pdf ,  16,  "Helvetica",  "WinAnsiEncoding" ) ; 
cpdf_text ($pdf ,  100,  100,  "Algun  texto"); 
cpdf_end_text ( $pdf )  ?> 


Vea  tambien  cpdf_end_texL). 


cpdf_end_text  (PHP  3>=  3.0.8,  PHP  4  >=  4.0.0) 


Finaliza  una  seccion  de  texto 


void  cpdf_end_text  (int  pdf  document ) 


La  funcion  cpdf_end_text()  finaliza  unaseccion  de  texto  que  fue  inicializada  con  cpdf_begm_text0. 
Ejemplo  1.  Salida  de  texto 

<?php  cpdf_begin_text ($pdf )  ; 

cpdf_set_f ont ( $pdf ,  16,  "Helvetica",  "WinAnsiEncoding"); 
cpdf_text ($pdf ,  100,  100,  "Algun  texto"); 
cpdf_end_text ( $pdf )  ?> 
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Vea  tambien  cpdf_begin_text'). 


cpdf_show  (PHP  3>=  3.0.8,  PHP  4  >=  4.0.0) 

Muestra  el  texto  en  la  posicion  actual 

void  cpdf_show  (int  pdf  document ,  string  text) 

La  funcion  cpdf_show()  muestra  la  cadena  text  en  la  posixcion  actual. 
Vea  tambien  cpdf_text(),  cpdf_begin_textO,  cpdf_end_text'). 


cpdf_show_xy  (PHP  3>=  3.0.8,  PHP  4  >=  4.0.0) 


Muestra  texto  en  la  posicion 


void  cpdf_show_xy  (int  pdf  document ,  string  text,  double  x-koor,  double 
y-koor,  int  mode) 


La  funcion  cpdf_show_xy()  muestra  la  cadena  text  en  la  posicion  con  coordenadas  ( x-coor , 
y-coor).  El  ultimo  parametro  opcional  determina  la  longitud  de  la  unidad.  Si  es  0  o  se  omite,  se  usa  la 
unidad  por  defecto  especificada  para  la  pagina.  De  otro  modo  las  coordenadas  son  medidas  en  puntos 
postscript,  despreciando  la  unidad  actual. 

Nota:  La  funcion  cpdf_show_xy()  es  identica  a  cpdf_text[)  sin  el  parametro  opcional. 


Vea  tambien  cpdf  text)). 


cpdf_text 


(PHP  3>=  3.0.8,  PHP  4  >=  4.0.0) 


Muestra  texto  conparametros 


void  cpdf_text  (int  pdf  document ,  string  text, 
int  mode,  double  orientation,  int  alignmode) 


double  x-koor, 


double  y-koor, 
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La  funcion  cpdf_text()  muestra  la  cadena  text  en  la  posicion  de  coordenadas  ( x-coor ,  y-coor).  El 
paramero  opcional  determina  la  longitud  de  la  unidad.  Si  es  0  o  se  omite,  se  usa  la  unidad  por  defecto 
especificada  para  la  pagina.  De  otro  modo  las  coordenadas  son  medidas  en  puntos  postscript 
despreciando  la  unidad  actual.  El  parametro  opcional  orientation  es  la  rotacion  del  texto  en  grados. 
El  parametro  opcional  alignmode  determina  como  esta  alineado  el  texto.  Vea  la  documentation  de 
ClibPDF  para  los  posibles  valores. 

Vea  tambien  cpdf_show_xy '). 


cpdf_set_font  (PHP  3>=  3.0.8,  PHP  4  >=  4.0.0) 

Selecciona  la  fuente  y  el  tamano  actual 

void  cpdf_set_font  (int  pdf  document ,  string  font  name,  double  size,  string 
encoding) 


La  funcion  cpdf_set_font()  define  la  fuente  actual,  el  tamano  y  la  codificacion.  Actualmente  solo  son 
soportadas  las  fuentes  estandar  de  postscript.  El  ultimo  parametro  encoding  puede  tomar  los 
siguientes  valores:  "MacRomanEncoding",  "MacExpertEncoding",  "WinAnsiEncoding",  y  "null", 
"null"  es  para  el  cifrado  inclufdo  en  la  fuente.  Para  mas  information  vea  el  manual  de  ClibPDF, 
especialmente  para  como  soportar  las  fuentes  asiaticas. 


cpdf_set_leading  (PHP  3>=  3.0.8,  PHP  4  >=  4.0.0) 

Define  la  distancias  entre  las  lfneas  de  texto 

void  cpdf_set  leading  (int  pdf  document ,  double  distance) 

La  funcion  cpdf_set_leading()  define  la  distancia  entre  las  lfneas  de  texto.  Esto  se  usara  si  el  texto  es  la 
salida  de  cpdf_continue_text0. 

Vea  tambien  cpdf_continue_textO. 

cpdf_set_text_rendering  php  3>=  3.0.8,  php  4  >=  4  0  o> 

Determina  como  es  presentado  el  texto 

void  cpdf_set_text_rendering  (int  pdf  document ,  int  mode) 
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La  funcion  cpdf_set_text_rendering()  determina  como  es  presentado  el  texto.  Los  posibles  valores  para 
mode  son  0=llenar  texto,  l=poner  texto,  2=llenar  y  poner  texto,  3=invisible,  4=llenar  texto  y  anadirlo  al 
camino  de  corte,  5=poner  texto  y  anadirlo  al  camino  de  corte,  6=llenar  y  poner  texto  y  anadirlo  al  camino 
de  corte,  7=anadirlo  al  camino  de  corte 


cpdf_set_horiz_scaling  (php  3>=  3.0.8,  php  4  >=  4 .0.0 

Define  la  escala  horizontal  del  texto 

void  cpdf_set_horiz_scaling  (int  pdf  document,  double  scale) 


La  funcion  cpdf_set_horiz_scaling()  define  la  escala  horizontal  al  scale  por  ciento. 


cpdf_set_text_rise  (PHP  3>=  3.0.8,  PHP  4  >=  4.0.0) 

Define  la  elevacion  del  texto 

void  cpdf_set_text_rise  (int  pdf  document ,  double  value ) 


La  funcion  cpdf_set_text_rise()  define  la  elevacion  del  texto  a  value  unidades. 


cpdf_set_text_matrix  (php  3>=  3.0.8,  php  4  >=  4.0.0 

Define  la  matriz  de  texto 

void  cpdf_set_text_matrix  (int  pdf  document ,  array  matrix ) 


La  funcion  cpdf_set_text_matrix()  define  una  matriz  que  describe  una  transformation  aplicada  a  la 
fuente  actual  de  texto. 


203 


ClibPDF 


cpdf_set_text_pos  (PHP  3>=  3.0.8,  PHP  4  >=  4.0.0) 


Define  la  posicion  del  texto 


void  cpdf_set_text_pos  (int  pdf  document ,  double  x-koor,  double  y-koor ,  int 
mode) 


La  funcion  cpdf_set_text_pos()  define  la  posicion  del  texto  para  la  siguiente  llamada  a  cpdf_showO- 

El  ultimo  parametro  opcional  mode  determina  la  longitud  de  la  unidad.  Si  es  0  o  se  omite,  se  usa  el  valor 
por  defecto  para  la  pagina.  De  otro  modo,  las  coordenadas  son  medidas  en  puntos  postscript, 
despreciando  la  unidad  actual. 

Vea  tambien  cpdf_show'),  cpdf_text'). 


cpdf_set_char_spacing  (php  3>=  3.0.8,  php  4  >=  4.0.0 

Determina  el  espacio  entre  caracteres 

void  cpdf_set_char_spacing  (int  pdf  document,  double  space) 


LA  funcion  cpdf_set_char_spacing()  define  el  espacio  entre  caracteres. 
Vea  tambien  cpdf_set_word_spacing\),  cpdf_set_leading\). 


cpdf_set_word_spacing  (php3>=  3.0.8,  php  4>=  4.0.0 

Define  el  espacio  entre  palabras 

void  cpdf_set_word_spacing  (int  pdf  document ,  double  space) 


La  funcion  cpdf_set_word_spacing()  especifica  el  espacio  entre  palabras. 
Vea  tambien  cpdf_set_char_spacing '),  cpdf_set_leading  j. 


cpdf_continue_text  (php  3>=  3.0.8,  php  4  >=  4.0.0 


Pone  texto  en  la  lfnea  siguiente 
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void  cpdf_continue_text  (int  pdf  document ,  string  text) 

La  funcion  cpdf_continue_text()  pone  la  cadena  text  en  la  lfnea  siguiente. 

Vea  tambien  cpdf_show_xy '),  cpdf_text(),  cpdt'  set  leading  'j,  cpdf_set_text_pos(). 

cpdf_stringwidth  (php  3>=  3.0.8,  php  4  >=  4.0.0 

Devuelve  la  anchura  del  texto  en  la  fuente  actual 

double  cpdf_stringwidth  (int  pdf  document ,  string  text) 

La  funcion  cpdf_stringwidth()  devuelve  la  anchura  de  la  cadena  text.  Requiere  haber  definido  antes 
una  fuente. 

Vea  tambien  cpdfsetfonb). 

cpdf_save  (PHP  3>=  3.0.8,  PHP  4  >=  4.0.0) 

Salva  el  entorno  actual 

void  cpdf_save  (int  pdf  document) 

La  funcion  cpdf_save()  salva  el  entorno  actual.  Funciona  como  el  comando  gsave  de  postscript.  Muy  util 
si  se  quiere  trasladar  o  trotar  un  objeto  sin  afetar  a  los  demas. 

Vea  tambien  cpdf_restore '). 

cpdf_restore  (PHP  3>=  3.0.8,  PHP  4  >=  4.0.0) 

Restaura  un  entorno  formalmente  salvado 

void  cpdf_restore  (int  pdf  document) 

La  funcion  cpdf_restore()  restaura  el  entorno  salvado  con  cpdf_save ').  Funciona  como  el  comando 
grestore  de  postscript.  Muy  util  si  se  quiere  trasladar  o  rotar  un  objeto  sin  afectar  ortros  objetos. 
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Ejemplo  1.  Salvar/Restaurar 

<?php  cpdf_save ($pdf) ; 

//  hacer  todo  tipo  de  rotaciones,  transformaciones,  ... 
cpdf_restore ( $pdf )  ?> 


Vea  tambien  cpdf_save(). 


cpdf_translate  (PHP  3>=  3.0.8,  PHP  4  >=  4.0.0) 


Define  el  sistema  de  origen  de  coordenadas 


void  cpdf_translate  (int  pdf  document ,  double  x-koor,  double  y-koor,  int 
mode) 


La  funcion  cpdf_translate()  define  el  sistema  origen  de  coordenadas  en  el  punto  ( x-coor ,  y-coor). 

El  ultimo  parametro  opcional  determina  la  longitud  de  la  unidad.  Si  es  0  o  se  omite,  se  usa  la  unidad  por 
defecto  especificada  en  la  pagina.  De  otro  modo  las  coordenadas  son  medidas  en  puntos  postscript, 
depreciando  la  unidad  actual. 


cpdf_scale  (PHP  3>=  3.0.8,  PHP  4  >=  4.0.0) 

Define  la  escala 

void  cpdf_scale  (int  pdf  document ,  double  x-scale,  double  y-scale) 


La  funcion  cpdf_scale()  define  el  factor  de  escala  en  los  dos  sentidos. 


cpdf_rotate  (PHP  3>=  3.0.8,  PHP  4  >=  4.0.0) 

Define  la  rotacion 


void  cpdf_rotate  (int  pdf  document ,  double  angle ) 


La  funcion  cpdf_rotate()  define  la  rotacion  en  angle  grados. 
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Define  la  monotonia 

void  cpdf_setflat  (int  pdf  document ,  double  value) 


La  funcion  cpdf_setflat()  pone  la  monotonia  a  un  valor  de  entre  0  y  100. 


cpdf_setlinejoin  (PHP  3>=  3.0.8,  PHP  4  >=  4.0.0) 

Define  el  parametro  linejoin 

void  cpdf_setline join  (int  pdf  document ,  long  value) 


La  funcion  cpdf_setlinejoin()  define  el  parametro  entre  un  valor  de  0  y  2.  0  =  ingletes,  1  =  redondear,  2 
=  angulo  oblfcuo 


cpdf_setlinecap  (PHP  3>=  3.0.8,  PHP  4  >=  4.0.0) 

Define  el  parametro  linecap 

void  cpdf_setlinecap  (int  pdf  document ,  int  value) 


La  funcion  cpdf_setlinecap()  define  el  parametro  linecap  entre  los  valores  0  y  2.  0  =  empalmar  al  final,  1 
=  redondear,  2  =  esquina  proyectada 


cpdf_setmiterlimit  (php  3>=  3.0.8,  php  4  >=  4  0  0> 

Define  el  lfmite  del  inglete 

void  cpdf_setmiterlimit  (int  pdf  document,  double  value) 


La  funcion  cpdf_setmiterlimit()  define  el  lfmite  del  inglete  a  un  valor  mayor  o  igual  a  1 . 
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Define  la  profundidad  de  la  lfnea 

void  cpdf_setlinewidth  (int  pdf  document ,  double  width) 


La  funcion  cpdf_setlinewidth()  define  la  preofundidad  de  la  lfnea  a  width. 


cpdf_setdash  (PHP  3>=  3.0.8,  PHP  4  >=  4.0.0) 

Defina  el  patron  de  la  raya 

void  cpdf_setdash  (int  pdf  document ,  double  white,  double  black) 


La  funcion  cpdf_setdash()  define  el  patron  de  la  raya  white  unidades  blancas  y  black  unidades 
negras.  Si  los  dos  son  0  se  pone  una  lfnea  solida. 


cpdf_moveto  (PHP  3>=  3.0.8,  PHP  4  >=  4.0.0) 

Define  el  punto  actual 

void  cpdf_moveto  (int  pdf  document ,  double  x-koor,  double  y-koor,  int  mode) 


La  funcioncpdf_moveto()  pone  el  punto  actual  en  las  coordenadas  x-koor  y  y-koor. 

El  ultimo  parametro  opcional  determina  la  longitud  de  la  unidad.  Si  es  0  o  se  omite,  la  unidad  por  defecto 
sera  la  especificada  para  la  pagina.  De  otro  modo  las  coordenadas  se  mediran  en  puntos  postscript 
despreciando  la  unidad  en  curso. 


cpdf_rmoveto  (PHP  3>=  3.0.9,  PHP  4  >=  4.0.0) 

Define  el  punto  actual 

void  cpdf_rmoveto  (int  pdf  document ,  double  x-koor,  double  y-koor,  int  mode) 
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La  funcion  cpdf_rmoveto()  pone  el  punto  actual  relativo  a  las  coordenadas  x-koor  y  y-koor. 

El  ultimo  parametro  opciona  determina  la  loingitud  de  la  unidad.  Si  es  0  o  se  omite,  la  unidad  por  defecto 
sera  la  especificada  para  la  pagina.  De  otro  modo  las  coordenadas  se  mediran  en  puntos  postscript, 
despreciando  la  unidad  en  curso. 

Vea  tambien  cpdf_moveto  ')- 


cpdf_curveto  (PHP  3>=  3.0.8,  PHP  4  >=  4.0.0) 


Dibuja  una  curva 


void  cpdf_curveto  (int  pdf  document ,  double  xl,  double  yl,  double  x2,  double 
y2,  double  x3,  double  y3,  int  mode) 


La  funcion  cpdf_curveto()  dibuja  una  curva  Bezier  desde  el  punto  actual  al  punto  (x3,  y3 )  usando  (xl, 
yl)  y  ( x2 ,  y2)  como  puntos  de  control. 

El  ultimo  parametro  opcional  especifica  el  tamano  de  la  unidad.  Si  es  0  o  se  omite,  se  usa  la  unidad 
especificada  para  la  pagina.  De  otro  modo  las  coordenadas  se  miden  en  puntos  postscript,  despreciando 
la  unidad  en  curso. 

Vea  tambien  cpdf_movetoO,  cpdfjmoveto '),  cpdfrlineto'j,  cpdf_lineto0. 


cpdfjineto  (PHP  3>=  3.0.8,  PHP  4  >=  4.0.0) 


Dibuja  una  lfnea 


void  cpdf_lineto 


(int  pdf  document , 


double  x-koor, 


double  y-koor, 


int  mode) 


La  funcion  cpdf_lineto()  dibuja  una  lfnea  desde  el  punto  actual  al  punto  con  coordenadas  ( x-koor , 
y-koor). 

El  ultimo  parametro  opcional  determina  el  tamano  de  la  unidad.  Si  es  0  o  se  omite,  se  usa  el  valor 
especificado  para  la  pagina  por  defecto.  De  otro  modo  las  coordenadas  se  miden  en  puntos  postscript, 
despreciando  la  unidad  actual. 

Vea  tambien  cpdf_moveto0,  cpdfjmoveto '),  cpdf_curvetoQ. 
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Dibuja  una  lfnea 


void  cpdf_rlineto  (int  pdf  document ,  double  x-koor,  double  y-koor,  int  mode) 


La  funcion  cpdf_rlineto()  dibuja  una  lfnea  desde  el  punto  actual  al  punto  relativo  con  coordenadas 

( x-koor ,  y-koor ). 

El  ultimo  parametro  opcional  determina  la  longitud  de  la  unidad.  Si  es  0  o  se  omite,  se  usa  el  valor  por 
defecto  para  la  pagina.  De  otro  modo  las  coordenadas  se  miden  en  puntos  postscript,  despreciando  la 
unidad  actual. 

Vea  tambien  cpdf_movetoO,  cpdfjmoveto '),  cpdf_curveto(). 


cpdf_circle  (PHP  3>=  3.0.8,  PHP  4  >=  4.0.0) 


Dibuja  un  cfrculo 


void  cpdf_circle  (int  pdf  document ,  double  x-koor,  double  y-koor,  double 
radius,  int  mode ) 


La  funcion  cpdf_circle()  dibuja  un  cfrculo  con  centra  en  el  punto  ( x-koor ,  y-koor)  y  radio  radius. 

El  ultimo  parametro  opcional  define  el  tamano  de  la  unidad.  Si  es  0  o  se  omite,  se  usa  el  valor  por 
defecto  para  la  pagina.  De  otro  modo  las  coordenadas  se  miden  en  puntos  postscript,  despreciando  la 
unidad  actual. 

Vea  tambien  cpdf_arc '). 


cpdf_arc  (PHP  3>=  3.0.8,  PHP  4  >=  4.0.0) 


Dibuja  un  arco 


void  cpdf_arc  (int  pdf  document ,  double  x-koor,  double  y-koor,  double  radius, 
double  start,  double  end,  int  mode) 


La  funcion  cpdf_arc()  dibuja  un  arco  con  el  centra  rn  el  punto  ( x-koor ,  y-koor )  y  radio  radius, 
empezando  en  el  angulo  start  y  terminando  en  el  angulo  end. 
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El  ultimo  parametro  opcional  especifica  el  tamano  de  la  unidad.  Si  es  0  o  se  omite,  se  usa  la  unidad 
especificada  por  defecto.  De  otro  modo  las  coordenadas  son  medidas  en  puntos  postscript.despreciando 
la  unidad  actual. 

Vea  tambien  cpdfcircle). 


cpdf_rect 


(PHP  3>=  3.0.8,  PHP  4  >=  4.0.0) 


Dibuja  un  rectangulo 


void  cpdf_rect  (int  pdf  document ,  double  x-koor, 
double  height,  int  mode) 


double  y-koor, 


double  width, 


La  funcion  cpdf_rect()  dibuja  un  rectangulo  con  su  esquina  inferior  izquierda  en  el  punto  ( x-koor , 
y-koor).  La  anchura  es  widgth.  La  altura  es  height. 

El  ultimo  parametro  opcional  define  el  tamano  de  la  unidad.  Si  es  0  o  se  omite,  se  usa  la  unidad  por 
defecto  especificada  para  la  pagina.  De  otro  modo  las  coordenadas  se  miden  en  puntos  postscript, 
despreciando  la  unidad  actual. 


cpdf_closepath  (PHP  3>=  3.0.8,  PHP  4  >=  4.0.0) 


Cierra  el  camino 


void  cpdf_closepath  (int  pdf  document) 


La  funcion  cpdf_closepath()  cierra  el  camino  actual. 


cpdf_stroke  (PHP  3>=  3.0.8,  PHP  4  >=  4.0.0) 

Dibuja  una  lfnea  a  lo  largo  del  camino 

void  cpdf_stroke  (int  pdf  document) 

La  funcion  cpdf_stroke()  dibuja  una  lfnea  a  lo  largo  del  camino  actual. 
Vea  tambien  cpdf_closepath cpdf_closepath_stroke')- 
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Cierra  el  camino  y  dibuja  una  lfnea  a  lo  largo  del  camino 


void  cpdf_closepath_stroke  (int  pdf  document) 


La  funcion  cpdf_closepath_stroke()  es  una  combination  de  cpdf_closepath')  y  cpdf_stroke  ').  Despues 
limpia  el  camino. 

Vea  tambien  cpdf_closepath '),  cpdt’_stroke'). 


cpdf_fill  (PHP  3>=  3.0.8,  PHP  4  >=  4.0.0) 

LLena  el  camino  actual 

void  cpdf_fill  (int  pdf  document) 

La  funcion  cpdf_fill()  llena  el  interior  del  camino  actual  con  el  color  alctual  de  relleno. 

Vea  tambien  cpdf_closepath '),  cpdf_stroke  (),  cpdf_setgray_filL),  cpdf_setgray(),  cpdf_setrgbcolor_filL), 
cpdf_setrgbcolor|). 


cpdf_fill_stroke  (PHP  3>=  3.0.8,  PHP  4  >=  4.0.0) 


LLena  y  traza  el  camino  actual 


void  cpdf_f ill_stroke  (int  pdf  document) 


La  funcion  cpdf_fill_stroke()  llena  el  interior  del  camino  actual  con  el  color  de  relleno  actual  y  dibuja  el 
camino  actual. 

Vea  tambien  cpdf_closepath(),  cpdf_stroke  [),  cpdf  fi  1 1 '  ),  cpdf_setgray_filL),  cpdf_setgray '), 
cpdf_setrgbcolor_fillO,  cpdf_setrgbcolor(). 


cpdf_closepath_f  ill_stroke  <php  3>=  3.0.8,  php  4  >=  4  0  o> 


Cierra,  llena  y  traza  el  camino  actual 
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void  cpdf_closepath_f ill_stroke  (int  pdf  document) 

La  funcion  cpdf_closepath_filI_stroke()  cierra,  llena  el  interior  del  caminoa  catual  con  el  color  actual  de 
relleno  y  dibuja  el  camino  actual. 

Vea  tambien  cpdf_closepath [),  cpdfstroke),  cpdf  till '),  cpdf_setgray_fill'),  cpdf_setgray(), 
cpdf_setrgbcolor_filL),  cpdf_setrgbcolor')- 

cpdf_clip  (PHP  3>=  3.0.8,  PHP  4  >=  4.0.0) 

Ajusta  al  camino  actual 

void  cpdf_clip  (int  pdf  document) 

La  funcion  cpdf_clip()  ajusta  todos  los  dibujos  al  camino  actual. 

cpdf_setgray_fill  (PHP  3>=  3.0.8,  PHP  4  >=  4.0.0) 

Pone  el  color  de  relleno  al  valor  gris 

void  cpdf_setgray_f ill  (int  pdf  document ,  double  value) 

La  funcion  cpdf_setgray_fill()  define  el  valor  de  gris  actual  para  rellelanr  un  camino. 

Vea  tambien  cpdf_setrgbcolor_fill '). 

cpdf_setg  ray_stroke  <php  3>=  s.o.s,  php  4  >=  4.0.0) 

Define  el  color  para  dibujar  al  valor  gris 

void  cpdf_setgray_stroke  (int  pdf  document ,  double  gray  value) 

La  funcion  cpdf_setgray_stroke()  pone  el  color  de  dibujo  actual  al  valor  de  gris  dado. 

Vea  tambien  cpdf_setrgbcolor_stroke '). 
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Pone  el  color  de  relleno  y  dibujo  a  gris 

void  cpdf_setgray  (int  pdf  document ,  double  gray  value) 

La  funcion  cpdf_setgray_stroke  )  pone  el  color  de  relleno  y  dibujo  al  color  gris  dado. 
Vea  tambien  cpdf_setrgbcolor_stroke  (),  cpdf_setrgbcolor_fill '). 


cpdf_setrgbcolor_f  ill  (php  3>=  3.o.8,  php  4  >=  4  .o  .o 


Pone  el  color  de  relleno  a  1  valor  de  clor  rgb 


void  cpdf_setrgbcolor_f ill  (int  pdf  document ,  double  red  value,  double  green 
value,  double  blue  value ) 


La  funcion  cpdf_setrgbcolor_fill()  pone  el  color  rgb  actual  para  rellenar  un  camino. 
Vea  tambien  cpdf_setrgbcolor_stroke  (),  cpdf_setrgbcolor)). 


cpdf_setrgbcolor_stroke  (php 3>=  3.o.8,  php 4 >=  4.0.0 


Pone  el  color  de  dibujo  al  valor  de  color  rgb 


void  cpdf_setrgbcolor_stroke  (int  pdf  document,  double  red  value,  double 
green  value,  double  blue  value) 


La  funcion  cpdf_setrgbcolor_stroke()  pone  el  color  de  dibujo  actual  al  valor  de  color  rgb  dado. 
Vea  tambien  cpdf_setrgbcolor_fill  [),  cpdf_setrgbcolor  ). 


cpdf_setrgbcolor  (php  3>=  3  0 8  php 4 >=  4.0.0 


Pone  el  color  de  relleno  y  dibujo  al  valor  de  color  rgb 
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void  cpdf_setrgbcolor  (int  pdf  document ,  double  red  value,  double  green 
value,  double  blue  value) 


La  funcion  cpdf_setrgbcolor_stroke ')  pone  el  color  de  relleno  y  dibujo  actual  al  color  rgb  dado. 
Vea  tambien  cpdf_setrgbcolor_stroke '),  cpdf_setrgbcolor_fill 


cpdf_add_outline  (PHP  3>=  3.0.9,  PHP  4  >=  4.0.0) 


Anade  una  marca  en  la  pagina  actual 


void  cpdf_add_outline  (int  pdf  document ,  string  text) 


La  funcion  cpdf_add_outline()  anade  una  marca  con  el  texto  text  que  apunta  a  la  pagina  actual. 

Ejemplo  1.  Anadiendo  un  contorno  de  pagina 

<?php 

$cpdf  =  cpdf_open ( 0 ) ; 

cpdf_page_init ( $cpdf ,  1,  0,  595,  842); 
cpdf_add_outline ( $cpdf ,  0,  0,  0,  1,  "Pagina  1"); 

//  ... 

//  Algun  dibujo 

II... 

cpdf_f inalize ( $cpdf ) ; 

Header ( "Content-type :  application/pdf " ) ; 
cpdf_output_buf fer ( $cpdf ) ; 
cpdf_close ($cpdf ) ; 

?> 


cpdf_set_page_animation  (php 3>=  309  php 4 >=  4 0 0) 


Define  la  separacion  entre  paginas 


void  cpdf_set_page_animation  (int  pdf  document ,  int  transition,  double 
duration) 


215 


ClibPDF 


La  funcion  cpdf_set_page_animation()  define  la  transicion  entre  paginas  que  se  siguen. 
El  valor  de  transition  puede  ser 


0  para  ninguno, 

1  para  dos  lmeas  que  se  barren  a  traves  de  la  pantalla,  revelen  la  pagina, 

2  para  multiples  lmeas, 

3  para  que  una  caja  revele  la  pagina, 

4  para  una  unica  lfnea, 

5  para  que  la  pagina  naterior  se  disipe  para  revelar  la  pagina, 

6  para  que  el  efecto  de  disolucion  se  mueva  de  un  extremop  de  la  pagina  al  otro, 

7  para  que  la  pagina  antfgua  simplemente  sea  reemplazada  por  la  nueva  pagina  (default) 

El  valor  de  duration  es  el  numero  de  segundos  entre  las  paginas  que  se  pasan. 


cpdf Jmport  Jpeg  <php  3>=  3.0.9,  php  4  >=  4 .0 .0) 


Abre  una  imagen  JPEG 


int  cpdf_open_jpeg  (int  pdf  document ,  string  file  name,  double  x-koor,  double 
y-koor,  double  angle,  double  width,  double  height,  double  x-scale,  double 
y-scale,  int  mode) 


La  funcion  cpdf_import_jpeg()  abre  una  imagen  almacenada  en  el  fichero  de  nombre  file  name.  El 
formato  de  la  imagen  debe  ser  JPEG.  La  imagen  es  situada  en  la  pagina  actual  en  la  posicion  ( x-koor , 
y-koor).  La  imagen  es  rotada  angle  grados. 

El  ultimo  parametro  opcional  determina  el  tamano  de  la  unidad.  Si  es  0  o  se  omite,  se  usa  la  unidad  por 
defecto  especificada  para  la  pagina.  De  otro  modo  las  coordenadas  se  miden  en  puntos  postscript, 
despreciando  la  unidad  actual. 

Vea  tambien  cpdf_place_inline_imageO, 


cpdf_place  inline Jmage  (php 3>=  3.0.9,  php 4 >=  4.0.o) 


Situa  una  imagen  en  la  pagina 


void  cpdf  place  inline  image  (int  pdf  document ,  int  image,  double  x-koor, 
double  y-koor,  double  angle,  double  width,  double  height,  int  mode) 


La  funcion  cpdf_place_inline_image()  situa  una  imagen  creada  con  las  funciones  de  imagenes  de  PHP 
en  la  posicion  de  la  pagina  ( x-koor ,  y-koor).  La  imagen  puede  ser  escalada  al  mismo  tiempo. 
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El  ultimo  parametro  opcional  determina  el  tamano  de  la  unidad.  Si  es  0  o  se  omite,  se  usa  la  unidad  por 
defecto  especificada  para  la  pagina.  De  otro  modo  las  coordenadas  son  medidas  en  puntos  postscript, 
descartando  la  unidad  actual. 

Vea  tambien  cpdf jmport  jpeg'), 


cpdf_add_an notation  (php  3>=  3012  php  4  >=  4.0.0 


Anade  una  anotacion 


void  cpdf_add_annotation  (int  pdf  document ,  double  llx,  double  lly ,  double 
urx,  double  ury ,  string  title,  string  content ,  int  mode) 


La  funcion  cpdf_add_annotation()  anade  una  nota  con  la  esquina  inferior  izquierda  en  (llx,  lly )  y  la 
esquina  superior  derecha  en  (urx,  ury). 

El  ultomo  parametro  opcional  determina  el  tamano  de  la  unidad.  Si  es  0  o  se  omite,  se  usa  la  unidad  por 
defecto  especificada  para  la  pagina.  De  otro  modo  las  coordenadas  se  miden  en  puntos  postscript, 
despreciando  la  unidad  actual. 
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XI.  CURL,  Client  URL  Library  Functions 

PHP  supports  libcurl,  a  library,  created  by  Daniel  Stenberg,  that  allows  you  to  connect  and  communicate 
to  many  different  types  of  servers  with  many  different  types  of  protocols,  libcurl  currently  supports  the 
http,  https,  ftp,  gopher,  telnet,  diet,  file,  and  Map  protocols,  libcurl  also  supports  HTTPS  certificates, 
HTTP  POST,  HTTP  PUT,  FTP  uploading  (this  can  also  be  done  with  PHP’s  ftp  extension),  HTTP  form 
based  upload,  proxies,  cookies  and  user+password  authentication. 

In  order  to  use  the  CURL  functions  you  need  to  install  the  CURL  (http://curl.haxx.se/)  package.  PHP 
requires  that  you  use  CURL  7.0.2-beta  or  higher.  PHP  will  not  work  with  any  version  of  CURL  below 
version  7.0.2-beta. 

To  use  PHP’s  CURL  support  you  must  also  compile  PHP  — with-curl  [=dir]  where  DIR  is  the 
location  of  the  directory  containing  the  lib  and  include  directories.  In  the  "include"  directory  there  should 
be  a  folder  named  "curl"  which  should  contain  the  easy.h  and  curl.h  files.  There  should  be  a  file  named 
"libcurl. a"  located  in  the  "lib"  directory. 

These  functions  have  been  added  in  PHP  4.0.2. 

Once  you’ve  compiled  PHP  with  CURL  support,  you  can  begin  using  the  curl  functions.  The  basic  idea 
behind  the  CURL  functions  is  that  you  initialize  a  CURL  session  using  the  curl_init(),  then  you  can  set 
all  your  options  for  the  transfer  via  the  curl_exec  )  and  then  you  finish  off  your  session  using  the 
curl_close  ').  Here  is  an  example  that  uses  the  CURL  functions  to  fetch  the  PHP  homepage  into  a  file: 

Ejemplo  1.  Using  PHP’s  CURL  module  to  fetch  the  PHP  homepage 


<?php 

$ch  =  curl_init  ("http://www.php.net/"); 
$fp  =  fopen  ("php_homepage.txt",  "w"); 

curl_setopt  ($ch,  CURLOPT_INFILE,  $fp) ; 
curl_setopt  ($ch,  CURLOPT_HEADER,  0); 

curl_exec  ($ch); 
curl_close  ($ch) ; 
fclose  ( $  f p ) ; 

?> 
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curl  init(PHP4>=40  2) 


Initialize  a  CURL  session 


int  curl_init  (string  [url]) 


The  curl_init()  will  initialize  a  new  session  and  return  a  CURL  handle  for  use  with  the  curl_setopt(), 
curl_exec  '),  and  curl_close')  functions.  If  the  optional  url  parameter  is  supplied  then  the 
CURLOPT_URL  option  will  be  set  to  the  value  of  the  parameter.  You  can  manually  set  this  using  the 
curl_setopt ')  function. 

Ejemplo  1.  Initializing  a  new  CURL  session  and  fetching  a  webpage 

<?php 

$ch  =  curl_init(); 

curl_setopt  ($ch,  CURLOPT_URL,  "http://www.zend.com/"); 
curl_setopt  ($ch,  CURLOPT_HEADER,  0); 

curl_exec  ($ch) ; 

curl_close  ($ch) ; 

?> 


See  also:  curl_close  ),  curl_setopL) 


curl_setopt(PHP4>=4  0  2) 


Set  an  option  for  a  CURL  transfer 


bool  curl_setopt  (int  ch,  string  option,  mixed  value) 


The  curl_setopt()  function  will  set  options  for  a  CURL  session  identified  by  the  ch  parameter.  The 
option  parameter  is  the  option  you  want  to  set,  and  the  value  is  the  value  of  the  option  given  by  the 

option. 

The  value  should  be  a  long  for  the  following  options  (specified  in  the  option  parameter): 

•  CURLOP T_INF ILES I ZE:  When  you  are  uploading  a  file  to  a  remote  site,  this  option  should  be  used 
to  tell  PHP  what  the  expected  size  of  the  infile  will  be. 
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C URLOP  T_  VERB OSE:  Set  this  option  to  a  non-zero  value  if  you  want  CURL  to  report  everything  that 
is  happening. 

CURLOPT_HEADER:  Set  this  option  to  a  non-zero  value  if  you  want  the  header  to  be  included  in  the 
output. 

CURLOPT_NOPROGRESS:  Set  this  option  to  a  non-zero  value  if  you  don’t  want  PHP  to  display  a 
progress  meter  for  CURL  transfers 

Nota:  PHP  automatically  sets  this  option  to  a  non-zero  parameter,  this  should  only  be  changed  for 
debugging  purposes. 


CURLOPT_NOBODY:  Set  this  option  to  a  non-zero  value  if  you  don’t  want  the  body  included  with  the 
output. 

CURLOPT_FAILONERROR:  Set  this  option  to  a  non-zero  value  if  you  want  PHP  to  fail  silently  if  the 
HTTP  code  returned  is  greater  than  300.  The  default  behaviour  is  to  return  the  page  normally,  ignoring 
the  code. 

CURLOPT_UPLOAD:  Set  this  option  to  a  non-zero  value  if  you  want  PHP  to  prepare  for  an  upload. 

CURLOPT_POST:  Set  this  option  to  a  non-zero  value  if  you  want  PHP  to  do  a  regular  HTTP  POST. 
This  POST  is  a  normal  application/x-www-from-urlencoded  kind,  most  commonly  used  by  HTML 
forms. 

CURLOPT_FTPLISTONLY:  Set  this  option  to  a  non-zero  value  and  PHP  will  just  list  the  names  of 
an  FTP  directory. 

CURLOPT_FTP APPEND:  Set  this  option  to  a  non-zero  value  and  PHP  will  append  to  the  remote  file 
instead  of  overwriting  it. 

CURLOPT_NETRC :  Set  this  option  to  a  non-zero  value  and  PHP  will  scan  your  ~./netrc  file  to  find 
your  username  and  password  for  the  remote  site  that  you’re  establishing  a  connection  with. 

CURLOPT_FOLLOWLOCATION:  Set  this  option  to  a  non-zero  value  to  follow  any  "Location:  " 
header  that  the  server  sends  as  a  part  of  the  HTTP  header  (note  this  is  recursive,  PHP  will  follow  as 
many  "Location:  "  headers  that  it  is  sent.) 

CURLOPT_PUT:  Set  this  option  a  non-zero  value  to  HTTP  PUT  a  file.  The  file  to  PUT  must  be  set 
with  the  CURLOPTJNFILE  and  CURLOPTJNFILESIZE. 

CURLOPT_MUTE:  Set  this  option  to  a  non-zero  value  and  PHP  will  be  completely  silent  with  regards 
to  the  CURL  functions. 

CURLOPT_TIMEOUT:  Pass  a  long  as  a  parameter  that  contains  the  maximum  time,  in  seconds,  that 
you’ll  allow  the  curl  functions  to  take. 

CURLOPT_LOW_SPEED_LIMIT:  Pass  a  long  as  a  parameter  that  contains  the  transfer  speed  in 
bytes  per  second  that  the  transfer  should  be  below  during  CURLOPT_LOW_SPEED_TIME  seconds 
for  PHP  to  consider  it  too  slow  and  abort. 

CURLOP T_LOW_SPEED_T IME:  Pass  a  long  as  a  parameter  that  contains  the  time  in  seconds  that  the 
transfer  should  be  below  the  CURLOPT_LOW_SPEED_LIMIT  for  PHP  to  consider  it  too  slow  and 
abort. 


220 


CURL 


•  CURLOPT_RESUME_FROM:  Pass  a  long  as  a  parameter  that  contains  the  offset,  in  bytes,  that  you 
want  the  transfer  to  start  from. 

•  CURLOPT_S SLVERS ION:  Pass  a  long  as  a  parameter  that  contains  the  SSL  version  (2  or  3)  to  use. 
By  default  PHP  will  try  and  determine  this  by  itself,  although,  in  some  cases  you  must  set  this 
manually. 

•  CURLOPT_TIMECONDITION:  Pass  a  long  as  a  parameter  that  defines  how  the 
CURLOPT_TIMEVALUE  is  treated.  You  can  set  this  parameter  to  TIMECOND_IFMODSINCE  or 
TIMECOND_ISUNMODSINCE.  This  is  a  HTTP-only  feature. 

•  CURLOPT_TIMEVALUE :  Pass  a  long  as  a  parameter  that  is  the  time  in  seconds  since  January  1st, 
1970.  The  time  will  be  used  as  specified  by  the  CURLOPT_TIMEVALUE  option,  or  by  default  the 
TIMECOND_IFMODSINCE  will  be  used. 


The  value  parameter  should  be  a  string  for  the  following  values  of  the  option  parameter: 

•  CURLOPT_URL:  This  is  the  URL  that  you  want  PHP  to  fetch.  You  can  also  set  this  option  when 
initializing  a  session  with  the  curl_init')  function. 

•  CURLOPT_USERPWD:  Pass  a  string  formatted  in  the  [username]: [password]  manner,  for  PHP  to  use 
for  the  connection,  connection. 

•  CURLOPT_PROXYUSERPND:  Pass  a  string  formatted  in  the  [username]: [password]  format  for 
connection  to  the  HTTP  proxy. 

•  CURLOPT_RANGE:  Pass  the  specified  range  you  want.  It  should  be  in  the  "X-Y"  format,  where  X  or 
Y  may  be  left  out.  The  HTTP  transfers  also  support  several  intervals,  seperated  with  commas  as  in 
X-Y.N-M. 

•  CURLOPT_POSTFIELDS:  Pass  a  string  containing  the  full  data  to  post  in  an  HTTP  "POST" 
operation. 

•  CURLOP  T_REFERER:  Pass  a  string  containing  the  "referer"  header  to  be  used  in  an  HTTP  request. 

•  CURL  OP  T_  US  ERA  GEN  T :  Pass  a  string  containing  the  "user-agent"  header  to  be  used  in  an  HTTP 
request. 

•  CURLOPT_FTPPORT :  Pass  a  string  containing  the  which  will  be  used  to  get  the  IP  address  to  use  for 
the  ftp  "PORT"  instruction.  The  POST  instruction  tells  the  remote  server  to  connect  to  our  specified  IP 
address.  The  string  may  be  a  plain  IP  address,  a  hostname,  a  network  interface  name  (under  UNIX),  or 
just  a  plain  to  use  the  systems  default  IP  address. 

•  CURLOP  T_COOKIE:  Pass  a  string  containing  the  content  of  the  cookie  to  be  set  in  the  HTTP  header. 

•  CURLOP T_SSLCERT:  Pass  a  string  containing  the  filename  of  PEM  formatted  certificate. 

•  CURLOPT_SSLCERTPASSWD:  Pass  a  string  containing  the  password  required  to  use  the 
CURLOPT_SSLCERT  certificate. 

•  CURLOP T_COOKIEF I LE:  Pass  a  string  containing  the  name  of  the  file  containing  the  cookiee  data. 
The  cookie  file  can  be  in  Netscape  format,  or  just  plain  HTTP-style  headers  dumped  into  a  file. 

•  CURLOP T_CUSTOMREQUE ST:  Pass  a  string  to  be  used  instead  of  GET  or  HEAD  when  doing  an 
HTTP  request.  This  is  useful  for  doing  DELETE  or  another,  more  obscure,  HTTP  request. 
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Nota:  Don't  do  this  without  making  sure  your  server  supports  the  command  first. 


The  following  options  expect  a  file  descriptor  that  is  obtained  by  using  the  fopenfO  function: 

•  CURLOPT_FILE :  The  file  where  the  output  of  your  transfer  should  be  placed,  the  default  is 
STDOUT. 

•  CURLOPT_INFILE:  The  file  where  the  input  of  your  transfer  comes  from. 

•  CURLOPT_WRITEHEADER:  The  file  to  write  the  header  part  of  the  output  into. 

•  CURLOPT_STDERR :  The  file  to  write  errors  to  instead  of  stderr. 


curl_exec  (PHP  4  >=  4.0.2) 

Perform  a  CURL  session 

bool  curl_exec  (int  ch) 

This  function  is  should  be  called  after  you  initialize  a  CURL  session  and  all  the  options  for  the  session 
are  set.  Its  purpose  is  simply  to  execute  the  predefined  CURL  session  (given  by  the  ch). 

curl_close  (PHP  4  >=4.0.2) 

Close  a  CURL  session 

void  curl_close  (int  ch) 

This  functions  closes  a  CURL  session  and  frees  all  ressources.  The  CURL  handle,  ch.  is  also  deleted. 

curl_version  (php4>=4  0  2) 

Return  the  current  CURL  version 

string  curl_version  () 
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The  curl_version()  function  returns  a  string  containing  the  current  CURL  version. 


223 


XII.  Funciones  de  pago  electronico 

Estas  funciones  solo  estan  disponibles  si  el  interprete  ha  sido  compilado  con 
— with-cybercash=  [dir]  .  Estas  funciones  han  sido  anadidas  en  PHP4. 
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Cybercash 


??? 

array  cybercash_encr  (string  wmk,  string  sk,  string  inbuff) 


La  funcion  devuelve  un  array  asociativo  con  los  elementos  "errcode"  y,  si  "encode"  es  false,  "outbuff" 
(string),  "outLth"  (long)  y  "macbuff"  (string). 


cybercashdecr  {php  4  >=  4.o.0) 


??? 


array  cybercash_decr  (string  wmk,  string  sk,  string  inbuff) 


La  funcion  devuelve  un  anay  asociativo  con  los  elementos  "errcode"  y,  si  "errcode"  es  false,  "outbuff" 
(string),  "outLth"  (long)  y  "macbuff"  (string). 


cybercash_base64_encode  (php  4  >=  4.o.o) 

??? 


string  cybercash_base64_encode  (string  inbuff) 


cybercash_base64_decode  (PHP  4  >=  4 .0 .0 


string  cybercash_base64_decode  (string  inbuff) 
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XIII.  Credit  Mutuel  CyberMUT  functions 

This  extension  allows  you  to  process  credit  cards  transactions  using  Credit  Mutuel  CyberMUT  system  ( 
http://www.creditmutuel.fr/centre_commercial/vendez_sur_internet.html). 

CynerMUT  is  a  popular  Web  Payment  Service  in  France,  provided  by  the  Credit  Mutuel  bank.  If  you  are 
foreign  in  France,  these  functions  will  not  be  useful  for  you. 

These  functions  are  only  available  if  PHP  has  been  compiled  with  the  — with-cybermut  [=dir] 
option,  where  DIR  is  the  location  of  libcm-mac .  a  and  cm-mac .  h.  You  will  require  the  appropriate 
SDK  for  your  platform,  which  may  be  sent  to  you  after  your  CyberMUT’s  subscription  (contact  them  via 
Web,  or  go  to  the  nearest  Credit  Mutuel). 

The  use  of  these  functions  is  almost  identical  to  the  original  functions,  except  for  the  parameters  of 
return  for  cy hermut_creerformu  I  ai  recm ')  and  cybermut_creerreponsecm '),  which  are  returned  directly 
by  functions  PHP,  whereas  they  had  passed  in  reference  in  the  original  functions. 

These  functions  have  been  added  in  PHP  4.0.6. 

Nota:  These  functions  only  provide  a  link  to  CyberMUT  SDK.  Be  sure  to  read  the  CyberMUT 
Developers  Guide  for  full  details  of  the  required  parameters. 
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cybermut_creerformulairecm  (php  4  >=  4.0.5) 


Generate  HTML  form  of  request  for  payment 


string  cybermut_creerf ormulairecm  (string  url_CM,  string  version,  string  TPE , 
string  montant,  string  ref_commande,  string  texte_libre ,  string  url_retour , 
string  url_retour_ok ,  string  url_retour_err ,  string  langue,  string 
code_societe ,  string  t exte_bouton) 


cynermut_creerformuIairecm()  is  used  to  generate  the  HTML  form  of  request  for  payment. 

Ejemplo  1.  First  step  of  payment  (equiv  cgil.c) 


<?php 

/ /  Directory  where  are  located  the  keys 
putenv ( "CMKEYDIR=/var/ creditmut / cles "  )  ; 

/ /  Version  number 
$VERSION=" 1.2"; 


$retour  =  creditmut_creerf ormulairecm ( 

"https : / / www . creditmutuel . f r/test /telepaiement /paiement . cgi " , 
$VERSION, 

"1234567890", 

"300FRF", 

$REFERENCE, 

$TEXTE_LIBRE, 

$  URL_RE  TOUR , 

$URL_RETOUR_OK, 

$  URL_RE  T  OUR_E  RR , 

" f rancais " , 

"company" , 

"Paiement  par  carte  bancaire") ; 
echo  $retour; 

?> 


See  also  cybermut_testmac')  and  cybermut_creerreponsecm')- 


cybermut_testmac  <php  4  >=  4.0.5) 


Make  sure  that  there  no  was  data  diddling  contained  in  the  received  message  of  confirmation 
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bool  cybermut_testmac  (string  code_MAC ,  string  version,  string  TPE ,  string 
cdate,  string  montant ,  string  ref_commande,  string  texte_libre,  string 
code-retour ) 


cybermut_testmac()  is  used  to  make  sure  that  there  was  not  data  diddling  contained  in  the  received 
message  of  confirmation.  Pay  attention  to  parameters  code -retour  and  texte-libre,  which  cannot  be 
evaluated  as  is,  because  auf  the  dash.  You  must  retrieve  them  by  using: 

<?php 

$code_retour=$HTTP_GET_VARS [ "code-retour" ] ; 

$texte_libre=$HTTP_GET_VARS [ "texte-libre" ] ; 

?> 


Ejemplo  1.  Last  step  of  payment  (equiv  cgi2.c) 

<?php 

//  Make  sure  that  Enable  Track  Vars  is  ON. 

/ /  Directory  where  are  located  the  keys 
putenv ( "CMKEYDIR=/var/ creditmut / cles " ) ; 

/ /  Version  number 
$VERSION=" 1.2"; 

$texte_libre  =  $HTTP_GET_VARS [ "texte-libre "] ; 

$code_retour  =  $HTTP_GET_VARS [ "code-retour "] ; 

$mac_ok  =  creditmut_testmac ($MAC, $VERSION, $TPE, $date, $montant, $reference, $texte_libre, $code. 
if  ($mac_ok)  { 

// 

/ /  insert  data  processing  here 

// 

// 

$result=creditmut_creerreponsecm ( "OK" )  ; 

}  else  { 

$result=creditmut_creerreponsecm ( "Document  Falsifie") ; } 


?> 


See  also  c y  her m u  t_c  re c r f o rm  u  I  a i  rec  m ' )  and  c y  her m u  t_c  ree I'i'c po  n  s ec  m ' ) . 
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CyberMUT 


Generate  the  acknowledgement  of  delivery  of  the  confirmation  of  payment 

string  cybermut_creerreponsecm  (string  phrase) 


cybermut_creerreponsecm()  returns  a  string  containing  delivery  aknowledgement  message. 

The  parameter  is  "OK"  if  the  message  of  confirmation  of  the  payment  were  correctly  auhentified  by 
cy her m u t_te s tin ac  ' ) .  Any  other  chain  is  regarded  as  an  error  message. 

See  also  cybermut_creerformulairecm')  and  cybermut_testmao'). 
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XIV.  Character  type  functions 


Aviso 

This  module  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  these 
functions,  these  function  names,  in  concreto  ANYTHING  documented  here  can 
change  in  a  future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this 
module  at  your  own  risk. 


These  functions  check  whether  a  character  or  string  falls  into  a  certain  character  class  according  to  the 
current  locale. 

When  called  with  an  integer  argument  these  functions  behave  exactly  like  their  C  counterparts. 

When  called  with  a  string  argument  they  will  check  every  character  in  the  string  and  will  only  return 
true  if  every  character  in  the  string  matches  the  requested  criteria. 

Passing  anything  else  but  a  string  or  integer  will  return  false  immediately. 


Aviso 

These  functions  are  new  as  of  PHP  4.0.4  and  might  change  their  name  in  the  near 
future.  Suggestions  are  to  change  them  to  ctype_issomething()  instead  of 
ctype_something()  or  even  to  make  them  part  of  ext/standard  and  use  their 
original  C-names,  although  this  would  possibly  lead  to  further  confusion  regarding 
the  isset[)  vs.  is_sometype()  problem. 
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ctype 


Check  for  alphanumeric  character(s) 


bool  ctype_alnum  (string  c) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


See  also  setlocaleO- 


ctype_alpha  (php  4  >=  4 .0 .4) 


Check  for  alphabetic  character(s) 


bool  ctype_alpha  (string  c) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


ctype_cntrl  (php  4  >=  4 .0 .4) 


Check  for  control  character(s) 


bool  ctype_cntrl  (string  c) 
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Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


ctype_digit(PHP4>=4  0  4) 


Check  for  numeric  character(s) 


bool  ctype_digit  (string  c) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


ctypejower  (php  4  >=  4  o  4) 


Check  for  lowercase  character(s) 


bool  ctype_lower  (string  c) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 
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Check  for  any  printable  character(s)  except  space 


bool  ctype_graph  (string  c) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


ctype_print  (PHP  4  >=  4.0.4) 


Check  for  printable  character(s) 


bool  ctype_print  (string  c) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


ctype_punct  (PHP  4  >=  4.0.4) 


Check  for  any  printable  character  which  is  not  whitespace  or  an  alphanumeric  character 


bool  ctype_punct  (string  c) 
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Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


ctype_space  (PHP  4  >=4.0.4) 


Check  for  whitespace  character(s) 


bool  ctype_space  (string  c) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


ctype_upper  (PHP  4  >=4.0.4) 


Check  for  uppercase  character(s) 


bool  ctype_upper  (string  c) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 
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ctype 


Check  for  character(s)  representing  a  hexadecimal  digit 


bool  ctype_xdigit  (string  c) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 
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XV.  Funciones  de  la  capa  de  abstraccion  de 
bases  de  datos  (dbm-style) 

Estas  funciones  son  la  base  para  el  acceso  a  bases  de  datos  del  estilo  Berkeley  DB. 

Este  es  un  nivel  de  abstraccion  general  para  varias  bases  de  datos.  Como  tal  su  funcionalidad  esta 
limitada  a  un  grupo  de  modernas  bases  de  datos  como  Sleepycat  Software’s  DB2  ().  (Esta  no  debe 
confundirse  con  IBM  DB2  software,  la  cual  es  soportada  mediante  las  funciones  ODBC  ) 

El  comportamiento  de  varios  aspectos  depende  de  la  implementacion  de  la  base  de  datos.  Funciones 
como  dba_optimizeO  y  dba_sync ')  cumpliran  su  funcionalidad  con  unas  bases  de  datos  pero  no  con 
otras. 

Los  siguientes  manejadores  (handlers)  estan  soportados: 

•  dbm  es  el  mas  antiguo  (original)  tipo  de  base  de  datos  de  la  familia  de  Berkeley  DB.  Se  debe  evitar  su 
uso,  si  es  posible.  Nosotros  no  soportamos  las  funciones  de  compatibilidad  de  DB2  y  gdbm,  porque 
ellas  solo  son  compatibles  a  nivel  de  codigo  fuente,  pero  no  pueden  manejar  el  formato  original  dbm. 

•  ndbm  es  un  tipo  mas  nuevo  y  mas  flexible  que  dbm.  Todavia  tiene  la  mayoria  de  las  limitaciones  de 
dbm  (Por  lo  tanto  es  descartado). 

•  gdbm  es  el  gestor  de  bases  de  datos  de  GNU  (database  manager)  (). 

•  db2  es  Sleepycat  Software’s  DB2  ().  Es  descrito  como  "un  conjunto  de  herramientas  de  programacion 
que  proveen  acceso  de  alto  nivel  a  bases  de  datos  en  aplicaciones  standalone  o  en  el  modelo 
cliente/servidor.  " 

•  cdb  es  "una  rapida,  de  confianza,  sencilla  herramienta  para  la  creacion  y  lectura  de  bases  de  datos 
constantes."  Fue  creada  por  el  autor  de  qmail  y  puede  encontrarse  en  here  ().  Como  la  base  es 
constante  solo  se  soportan  las  operaciones  de  lectura. 


Ejemplo  1.  Ejemplo  de  DBA 

<?php 

$id  =  dba_open ( " /tmp/test . db" ,  "n",  "db2"); 

if ( ! $id)  { 

echo  "dba_open  failed\n"; 
exit; 

} 

dba_replace ( "key" ,  "This  is  an  example!",  $id); 

if (dba_exists ( "key "  ,  $ id) )  { 

echo  dba_fetch ( "key "  ,  $id)  ; 
dba_delete ( "key" ,  $id)  ; 

} 

dba_close ($id) ; 
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?> 


DBA  es  "binary  safe"  y  no  tiene  ningun  limite  arbitrario.  Hereda  todas  sus  limitaciones  de  la 
implementacion  de  base  de  datos  que  tenga. 

Todos  las  bases  de  datos  basadas  en  ficheros  deben  proveer  un  mecanismo  para  establecer  el  modo  a  la 
hora  de  crear  nuevas  bases  de  datos,  si  ello  es  posible.  Habitualmente  este  modo  es  pasado  como  el 
cuarto  argumento  en  dba_open ')  o  en  dba_popen  ). 

Se  puede  acceder  a  todas  las  entradas  de  una  base  de  datos  de  modo  secuencial  (lineal)  usando  las 
funciones  dba_firstl<ev ')  y  dba_nextkey No  se  puede  cambiar  la  base  de  datos  mientras  se  recorre 
(traversing)  por  ella. 

Ejemplo  2.  Recorriendo  una  base  de  datos 

<?php 

#  . . .open  database. . . 

$key  =  dba_firstkey ($id) ; 
while ($key  !=  false)  { 

if  ( . . . )  {  #  remember  the  key  to  perform  some  action  later 

$handle_later [ ]  =  $key; 

} 

$key  =  dba_nextkey ( $id) ; 

} 

for($i  =  0;  $i  <  count ($handle_later) ;  $i++) 

dba_delete ( $handle_later [ $ i ] ,  $id) ; 


?> 
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dba_close  (PHP  3>=  3.0.8,  PHP  4  >=  4.0.0) 


Cerrar  uba  base  de  datos 


void  dba_close  (int  handle) 


dba_close()  cierra  la  conexion  con  una  base  de  datos  previamente  abierta  y  libera  todos  los  recursos 
especificados  por  handle. 

handle  es  un  manejador  (handle)  de  la  base  de  datos  devuelto  por  dba_opcn '). 
dba_close()  no  devuelve  ningun  valor. 

Ver  tambien:  dba_open ')  dba  popen  ) 


dba_delete  (PHP  3>=  3.0.8,  PHP  4  >=  4.0.0) 

Borra  una  entrada  especificada  por  la  clave  key 

bool  dba_delete  (string  key,  int  handle) 

dba_delete()  borra  la  entrada  especificada  por  key  de  la  base  de  datos  especificada  por  handle, 
key  es  la  clave  de  la  entrada  que  es  borrada. 

handle  es  un  manejador  (handle)  de  la  base  de  datos  devuelto  por  dba_opcn '). 
dba_delete()  devuelve  true  o  false,  si  la  entrada  es  borrada  o  no,  respectivamente. 

Ver  tambien:  dba_exists()  dba_tetch ')  dba_insert')  dba_replace') 

dba_exists  (PHP  3>=  3.0.8,  PHP  4  >=  4.0.0) 

Comprueba  si  la  clave  key  existe 

bool  dba_exists  (string  key,  int  handle) 


dba_exists()  comprueba  si  la  clave  key  existe  en  la  base  de  datos  especificada  por  handle, 
key  es  la  clave  para  la  que  se  realiza  la  comprobacion. 

handle  es  un  manejador  (handle)  de  la  base  de  datos  devuelto  por  dba_opcn '). 
dba_exists()  devuelve  true  o  false,  si  la  clave  es  hallada  o  no,  respectivamente. 


238 


dba 


Ver  tambien:  dba_fetch' )  dba_delete')  dba_insert  )  dba_rcplace'j 


dba_fetch  (PHP  3>=  3.0.8,  PHP  4  >=  4.0.0) 

Extrae  los  datos  especificados  por  la  clave  key 

string  dba_fetch  (string  key,  int  handle) 


dba_fetch()  extrae  los  datos  especificados  por  la  clave  key  de  la  base  de  datos  determinada  por 

handle. 

key  es  la  clave  de  la  entrada  de  los  datos  que  queremos  extraer. 

handle  es  un  manejador  (handle)  de  la  base  de  datos  devuelto  por  dba_opcn '). 

dba_fetch()  devuelve  la  cadena  asociada  o  false,  si  el  par  key/data  es  hallado  o  no,  respectivamente. 

Ver  tambien:  dba_exists ')  dba_delete ')  dba_insert {)  dba_rcplace  ) 


dba_firstkey  (PHP  3>=  3.0.8,  PHP  4  >=  4.0.0) 

Conseguir  la  primera  clave 

string  dba_firstkey  (int  handle) 


dba_firstkey()  devuelve  la  primera  clave  de  la  base  de  datos  especificada  por  handle  y  resetea  el 
puntero  interno  de  claves.  Esto  permite  una  busqueda  lineal  por  toda  la  base  de  datos. 

handle  es  un  manejador  (handle)  de  la  base  de  datos  devuelto  por  dba_opcn '). 

dba_firstkey()  devuelve  la  clave  o  false  en  funcion  de  si  tiene  exito  o  falla,  respectivamente. 

Ver  tambien:  dba_nextkey )) 


dba_insert  (PHP  3>=  3.0.8,  PHP  4  >=  4.0.0) 
Insertar  una  entrada 


bool  dba_insert  (string  key,  string  value,  int  handle) 
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dba_insert()  inserta  la  entrada  descrita  con  key  y  value  dentro  de  la  base  de  datos  especificada  por 
handle.  Fallara  si  ya  existe  una  entrada  con  el  mismo  parametro  key. 

key  es  la  clave  de  la  entrada  a  ser  insertada. 

value  es  el  valor  a  ser  insertado. 

handle  es  un  manejador  (handle)  de  la  base  de  datos  devuelto  por  dba_opcn '). 
dba_insert()  devuelve  true  o  false,  en  funcion  de  si  tiene  exito  o  falla,  respectivamente. 

Ver  tambien:  dba_exists()  dba_delete ')  dba_fetch()  dba_replace() 


dba_nextkey  (PHP  3>=  3.0.8,  PHP  4  >=  4.0.0) 

Extraer  la  siguiente  clave 

string  dba_nextkey  (int  handle) 


dba_nextkey()  devuelve  la  siguiente  clave  de  la  base  de  datos  especificada  por  handle  e  incrementa  el 
puntero  de  claves  interno. 

handle  es  un  manejador  (handle)  de  la  base  de  datos  devuelto  por  dba_opcn )). 
dba_nextkey()  devuelve  la  clave  o  false  dependiendo  de  si  tiene  exito  o  falla,  respectivamente. 

Ver  tambien:  dba  firstkey  ) 


dba_popen  (PHP  3>=  3.0.8,  PHP  4  >=  4.0.0) 

Apertura  persistente  de  una  base  de  datos 

int  dba_popen  (string  path,  string  mode,  string  handler  [,  ...]) 


dba_popen()  establece  una  instancia  persistente  para  path  con  mode  usando  handler, 
path  normalmente  es  el  "path"  en  el  sistema  de  ficheros. 

mode  es  "r"  para  acceso  de  lectura,  "w"  para  lectura/escritura  de  una  base  de  datos  ya  existente,  "c"  para 
lectura/escritura  y  creacion  de  una  base  datos  si  esta  no  existe,  y  "n"  para  crear,  truncar  y 
lectura/escritura. 

handler  es  el  nombre  del  manejador  (handler)  que  sera  usado  para  el  acceso  al  path.  Es  pasado  como 
un  parametro  opcional  a  dba_popen()  y  puede  usarse  en  lugar  de  ella. 

dba_popen()  devuelve  un  valor  positivo  de  handler  o  false,  en  el  caso  de  que  la  apertura  de  la  base  de 
datos  se  realice  o  si  falla,  respectivamente. 
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Ver  tambien:  tlba_open ')  dba_close') 


dba_open  (PHP  3>=  3.0.8,  PHP  4  >=  4.0.0) 
Abrir  una  base  de  datos 


int  dba_open  (string  path,  string  mode,  string  handler  [,  ...]) 


dba_open()  establece  una  instancia  para  path  con  mode  usando  handler, 
path  normalmente  es  el  "path"  en  el  sistema  de  ficheros. 

mode  es  "r"  para  acceso  de  lectura,  "w"  para  lectura/escritura  de  una  base  de  datos  ya  existente,  "c"  para 
lectura/escritura  y  creacion  de  una  base  datos  si  esta  no  existe,  y  "n"  para  crear,  truncar  y 
lectura/escritura. 

handler  es  el  nombre  de  el  manejador  (handler)  que  sera  usado  para  el  acceso  al  path.  Es  pasado 
como  un  parametro  opcional  a  dba_open()  y  puede  usarse  en  lugar  de  ella. 

dba_open()  devuelve  un  valor  positivo  de  handler  o  false,  en  el  caso  de  que  la  apertura  de  la  base  de 
datos  se  realice  o  si  falla,  respectivamente. 

Ver  tambien:  dba  popcn ')  dba_close') 


dba_optimize  (PHP  3>=  3.0.8,  PHP  4  >=  4.0.0) 


Optimiza  la  base  de  datos 


bool  dba_optimize  (int  handle) 


dba_optimize()  optimiza  la  base  de  datos  especificada  por  handle, 
handle  es  un  manejador  (handle)  de  la  base  de  datos  devuelto  por  dba_opcn '). 
dba_optimize()  devuelve  true  o  false,  si  la  optimizacion  tiene  exito  o  falla,  respectivamente. 
Ver  tambien:  dba_sync  j 


dba_replace  (PHP  3>=  3.0.8,  PHP  4  >=  4.0.0) 


Reemplaza  o  inserta  una  entrada 
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bool  dba_replace  (string  key,  string  value,  int  handle) 


dba_replace()  reemplaza  o  inserta  la  entrada  descrita  con  key  y  value  dentro  de  la  base  de  datos 
especificada  por  handle. 

key  es  la  clave  de  la  entrada  a  insertar. 

value  es  el  valor  a  ser  insertado. 

handle  es  un  manejador  (handle)  de  la  base  de  datos  devuelto  por  dba_opcn '). 
dba_replace()  devuelve  true  o  false,  dependiendo  de  si  tiene  exito  o  falla  respectivamente. 

Ver  tambien:  dba_exists()  dba_delete))  dba_fetch')  dba_insert() 


dba_sync  (PHP  3>=  3.0.8,  PHP  4  >=  4.0.0) 

Sincroniza  la  base  de  datos 


bool  dba_sync  (int  handle) 


dba_sync()  sincroniza  la  base  de  datos  especificada  por  handle.  Esto  probablemente  realice  una 
escritura  fisica  en  el  disco,  si  es  soportado. 

handle  es  un  manejador  (handle)  de  la  base  de  datos  devuelto  por  dba_opcn '). 
dba_sync()  devuelve  true  o  false,  si  la  sincronizacion  tiene  exito  o  falla,  respectivamente. 

Ver  tambien:  dba_optimizeO 
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checkdate  (PHP  3,  PHP  4  >=  4.0.0) 

valida  una  fecha  u  hora 


int  checkdate  (int  month,  int  day,  int  year) 


Devuelve  un  valor  verdadero  si  la  fecha  dada  es  valida;  en  caso  contrario,  devuelve  un  valor  falso. 
Comprueba  la  validez  de  la  fecha  formada  por  los  argumentos.  Se  considera  valida  una  fecha  si: 

•  el  ano  esta  entre  0  y  32767,  ambos  incluidos 

•  el  mes  esta  entre  1  y  12,  ambos  incluidos 

•  el  dfa  esta  en  el  rango  permitido  para  el  mes  dado.  Se  tienen  en  consideration  los  anos  bisiestos. 


date  (PHP  3,  PHP  4  >=  4.0.0) 

da  formato  a  la  fecha/hora  local 

string  date  (string  format,  int  [timestamp] ) 


Devuelve  una  cadena  formateada  de  acuerdo  con  la  cadena  de  formato  dada,  utilizando  el  valor  de 
timestamp  dado  o  la  hora  local  actual  si  no  hay  parametro. 

Se  reconocen  los  siguientes  caracteres  en  la  cadena  de  formato: 

•  a  -  "am"  o  "pm" 

•  A  -  "AM"  o  "PM" 

•  d  -  dfa  del  mes,  dos  dfgitos  con  cero  a  la  izquierda;  es  decir,  de  "01"  a  "31" 

•  D  -  dfa  de  la  semana,  en  texto,  con  tres  letras;  por  ejemplo,  "Fri" 

•  F  -  mes,  en  texto,  completo;  por  ejemplo,  "January" 

•  h  -  hora,  de  "01"  a  "12" 

•  H  -  hora,  de  "00"  a  "23" 

•  g  -  hour,  sin  ceros,  de  "1"  a  "12" 

•  G  -  hour,  sin  ceros;  de  "0"  a  "23" 

•  i  -  minutos;  de  "00"  a  "59" 

•  j  -  dfa  del  mes  sin  cero  inicial;  de  "1"  a  "31" 

•  1  (’L’  minuscula)  -  dfa  de  la  semana,  en  texto,  completo;  por  ejemplo,  "Friday" 
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•  L  -  "1"  or  "0",  segun  si  el  ano  es  bisiesto  o  no 

•  m  -  mes;  de  "01"  a  "12" 

•  n  -  mes  sin  cero  inicial;  de  "1"  a  "12" 

•  M  -  mes,  en  texto,  3  letras;  por  ejemplo,  "Jan" 

•  s  -  segundos;  de  "00"  a  "59" 

•  S  -  sufijo  ordinal  en  ingles,  en  texto,  2  caracteres;  por  ejemplo,  "th",  "nd" 

•  t  -  numero  de  dias  del  mes  dado;  de  "28"  a  "31" 

•  U  -  segundos  desde  el  valor  de  ’epoch’ 

•  w  -  dia  de  la  semana,  en  numero,  de  "0"  (domingo)  a  "6"  (sabado) 

•  Y  -  ano,  cuatro  cifras;  por  ejemplo,  "1999" 

•  y  -  ano,  dos  cifras;  por  ejemplo,  "99" 

•  z  -  dia  del  ano;  de  "0"  a  "365" 

•  Z  -  diferencia  horaria  en  segundos  (de  "-43200"  a  "43200") 

Los  caracteres  no  reconocidos  se  imprimen  tal  cual.  El  formato  "Z"  siempre  devuelve  "0"  en  la  funcion 

gmdate()() 

Ejemplo  1.  Ejemplo  de  date() 

print  (dateC'l  dS  of  F  Y  h:i:s  A")); 

print  ("July  1,  2000  is  on  a  "  .  dateC'l",  mktime  (0,  0,  0, 7,  1, 2000)  )  )  ; 


Es  posible  usar  date()  y  mktime  )  juntas  para  obtener  fechas  futuras  o  pasadas. 

Ejemplo  2.  Ejemplo  de  date()  y  mktime  ) 

$tomorrow  =  mktime (0, 0, 0, date ( "m" )  , date ("d") +1, date ("Y") ) ; 

$lastmonth  =  mktime ( 0 , 0 , 0 , date ( "m" ) -1 , date ( "d" ) ,  date("Y")); 

$nextyear  =  mktime ( 0 , 0 , 0 , date ( "m" )  ,  date("d"),  date ("Y") +1) ; 


Para  dar  formato  a  fechas  en  otros  idiomas,  se  deben  usar  las  funciones  setlocale  )  y  strftime'). 
Ver  tambien  gmdate))  y  mktimeO- 


getdate  (PHP  3,  PHP  4  >=  4.0.0) 


obtiene  information  de  fecha  y  hora 
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array  getdate  (int  timestamp) 


Devuelve  un  array  asociativo  que  contiene  la  information  de  fecha  del  valor  timestamp  como  los 
siguientes  elementos: 

•  "seconds"  -  segundos 

•  "minutes"  -  minutos 

•  "hours"  -  horas 

•  "mday"  -  dfa  del  mes 

•  "wday"  -  dfa  de  la  semana,  en  numero 

•  "mon"  -  mes,  en  numero 

•  "year"  -  ano,  en  numero 

•  "yday"  -  dfa  del  ano,  en  numero;  por  ejemplo,  "299" 

•  "weekday"  -  dfa  de  la  semana,  en  texto,  completo;  por  ejemplo,  "Friday" 

•  "month"  -  mes,  en  texto,  completo;  por  ejemplo,  "January" 


gettimeofday  (PHP  3>=  3.0.7,  PHP  4  >=  4.0.0) 


obtiene  la  hora  actual 


array  gettimeofday  (void) 


Es  un  interfaz  para  gettimeofday(2).  Devuelve  un  array  asociativo  que  contiene  los  datos  devueltos  por 
esta  llamada  al  sistema. 

•  "sec"  -  segundos 

•  "usee"  -  microsegundos 

•  "minuteswest"  -  minutos  al  oeste  de  Greenwich 

•  "dsttime"  -  tipo  de  correction  dst 


gmdate  (PHP  3,  PHP  4  >=  4.0.0) 

da  formato  a  una  fecha/hora  GMT/CUT 
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string  gmdate  (string  format,  int  timestamp) 


Identica  a  la  funcion  data()  excepto  en  que  la  hora  devuelta  es  la  de  Greenwich  (GMT).  Por  ejemplo,  si 
se  utiliza  en  Finlandia  (GMT  +0200),  la  primera  lfnea  del  ejemplo  devuelve  "Jan  01  1998  00:00:00", 
mientras  la  segunda  imprime  "Dec  31  1997  22:00:00". 

Ejemplo  1.  Ejemplo  de  gmdate() 

echo  date (  "M  d  Y  H : i : s " , mkt ime (0,0,0,1,1,1998)  ); 
echo  gmdate (  "M  d  Y  H : i : s " , mkt ime ( 0 , 0 , 0 , 1 , 1 , 1 998 )  ); 


Ver  tambien  date)),  mktime))  y  gmmktime)). 

gmmktime  (php  3  php 4  >=  4 o o> 

obtiene  el  valor  timestamp  UNIX  de  una  fecha  GMT 

int  gmmktime  (int  hour,  int  minute,  int  second,  int  month,  int  day,  int  year 
{ ,  int  is_dst ] ) 

Identica  a  mktime'),  excepto  en  que  los  parametros  representan  una  fecha  GMT. 


gmstrftime  (PHP  3>=  3.0.12,  PHP  4  >=  4.0.0) 

da  formato  a  una  fecha/hora  GMT/CUT  segun  las  convenciones  locales 

string  gmstrftime  (string  format,  int  timestamp) 


Se  comporta  como  strftime '),  excepto  en  que  la  hora  devuelta  es  la  de  Greenwich  (GMT).  Por  ejemplo,  si 
se  utiliza  en  la  zona  horaria  EST  (GMT  -0500),  la  primera  lfnea  del  ejemplo  imprime  "Dec  31  1998 
20:00:00",  mientras  la  segunda  imprime  "Jan  01  1999  01:00:00". 

Ejemplo  1.  Ejemplo  de  gmstrftime() 

setlocale  ( ' LC_TIME'  ,  ' en_US'  ) ; 

echo  strftime  ("%b  %d  %Y  %H : %M : %S " , mktime (20 , 0 , 0 , 12 , 31 , 98 ) ) . " \n" ; 
echo  gmstrftime  ("%b  %d  %Y  %H : %M: %S " , mkt ime (20 ,  0 ,  0 ,  12 , 31 ,  98 ) )  . " \n" ; 
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Ver  tambien  strftime '). 


microtime  (PHP  3,  PHP  4  >=  4.0.0) 


devuelve  el  valor  timestamp  UNIX  actual  con  microsegundos 


string  microtime (void)  ; 


Devuelve  la  cadena  "msec  sec",  donde  sec  es  la  hora  actual  en  numero  de  segundos  desde  el  valor  Unix 
Epoch  (0:00:00  del  1  de  enero  de  1970,  hora  GMT),  y  msec  es  la  parte  de  microsegundos.  Esta  funcion 
solo  esta  disponible  en  sistemas  operativos  con  admiten  la  llamada  al  sistema  gettimeofday(). 

Ver  tambien  time'). 


mktime  (PHP  3,  PHP  4  >=  4.0.0) 


obtiene  el  timestamp  UNIX  de  una  fecha 


int  mktime  (int  hour,  int  minute,  int  second,  int  month,  int  day,  int  year  [, 
int  is_dst ] ) 


Advertencia:  Vease  el  extrano  orden  de  los  argumentos,  que  se  diferencia  del  orden  de  argumentos  en 
una  llamada  mktime()  de  UNIX  y  que  no  permite  eliminar  parametros  de  derecha  a  izquierda  (ver  abajo). 
Es  un  error  comun  mezclar  estos  valores  en  un  script. 

Devuelve  el  valor  timestamp  Unix  correspondiente  a  los  argumentos  dados.  El  timestamp  es  un  entero  de 
tipo  long  que  contiene  el  numero  de  segundos  entre  el  valor  Unix  Epoch  (1  de  enero  de  1970)  y  la  hora 
especificada. 

Se  pueden  eliminar  argumentos  en  orden  de  derecha  a  izquierda;  en  los  argumentos  omitidos  se  toma  el 
valor  de  la  fecha  y  hora  locales. 

is_dst  puede  ponerse  a  1  si  la  hora  corresponde  a  horario  de  verano,  0  si  no,  o  -1  (valor  por  omision) 
si  no  se  sabe. 

Nota:  is_dst  se  anadio  en  la  version  3.0.10. 


mktimeO  es  util  para  realizar  calculos  y  validaciones  con  fechas,  ya  que  calcula  automaticamente  el 
valor  correcto  para  una  entrada  fuera  de  rango.  Por  ejemplo,  cada  una  de  las  lmeas  siguientes  produce  la 
cadena  "Jan-01-1998". 
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Ejemplo  1.  Ejemplo  de  mktime() 

echo  date (  "M-d-Y",  mktime ( 0 , 0 , 0 , 12 , 32 , 1 9 97 )  ); 

echo  date (  "M-d-Y",  mktime (0, 0, 0, 13, 1, 1997)  ); 

echo  date (  "M-d-Y",  mktime ( 0 , 0 , 0 , 1 , 1, 1 998 )  ) ; 


El  ultimo  dia  de  cada  mes  se  puede  expresar  como  el  dia  "0"  del  mes  siguiente,  no  el  dia  -1.  Los  dos 
ejemplos  siguientes  producen  la  cadena  "The  last  day  in  Feb  2000  is:  29". 

Ejemplo  2.  El  ultimo  dia  del  proximo  mes 

$lastday=mkt ime (0,0,0,3,0,2000); 

echo  strftime ( "Last  day  in  Feb  2000  is:  %d" , $lastday) ; 

$lastday=mktime (0, 0, 0, 4, -31, 2000) ; 

echo  strftime ( "Last  day  in  Feb  2000  is:  %d" , $lastday ) ; 


Ver  tambien  date()  y  time )). 


strftime  (PHP  3,  PHP  4  >=  4.0.0) 

da  formato  a  la  hora  o  fecha  local  de  acuerdo  con  las  convenciones  locales 


string  strftime  (string  format,  int  timestamp) 


Devuelve  una  cadena  formateada  segun  la  cadena  de  formato  dada  utilizando  el  valor  timestamp  o  la 
hora  local  actual.  Los  nombres  del  mes  y  el  dia  de  la  semana  y  otras  cadenas  dependientes  del  idioma 
respetan  lo  establecido  con  setlocale '). 

Se  reconocen  los  siguientes  especificadores  de  conversion  en  la  cadena  de  formato: 

•  %a  -  nombre  del  dia  de  la  semana  abreviado 

•  %A  -  nombre  del  dia  de  la  semana  completo 

•  %b  -  nombre  del  mes  abreviado 

•  %B  -  nombre  del  mes  completo 

•  %c  -  representacion  de  fecha  y  hora  preferidas  en  el  idioma  actual 

•  %d  -  dia  del  mes  en  numero  (de  00  a  3 1) 

•  %H  -  hora  como  un  numero  de  00  a  23 

•  %I  -  hora  como  un  numero  de  01  a  12 
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•  %j  -  dfa  del  ano  como  un  numero  de  001  a  366 

•  %m  -  mes  como  un  numero  de  01  a  12 

•  %M  -  minuto  en  numero 

•  %p  -  ‘am’  o  ‘pm’,  segun  la  hora  dada,  o  las  cadenas  correspondientes  en  el  idioma  actual 

•  %S  -  segundos  en  numero 

•  %U  -  numero  de  la  semana  en  el  ano,  empezando  con  el  primer  domingo  como  el  primer  dfa  de  la 
primera  semana 

•  %W  -  numero  de  la  semana  en  el  ano,  empezando  con  el  primer  lunes  como  el  primer  dfa  de  la 
primera  semana 

•  %w  -  dfa  de  la  semana  en  numero  (el  domingo  es  el  0) 

•  %x  -  representacion  preferida  de  la  fecha  sin  la  hora 

•  %X  -  representacion  preferida  de  la  hora  sin  la  fecha 

•  %y  -  ano  en  numero  de  00  a  99 

•  %Y  -  ano  en  numero  de  cuatro  cifras 

•  %Z  -  nombre  o  abreviatura  de  la  zona  horaria 

•  %%  -  caracter  ‘%’ 

Ejemplo  1.  Ejemplo  de  strftime() 

setlocale  ( "LC_TIME " ,  "C"); 

print ( strftime (" %A  in  Finnish  is  ")); 
setlocale  ( "LC_TIME " ,  "fi_FI"); 

print ( strftime (" %A,  in  French  ")); 
setlocale  ( "LC_TIME " ,  "fr_CA"); 
print ( strftime (" %A  and  in  German  ")); 
setlocale  ( "LC_TIME " ,  "de_DE"); 

print ( strftime ( " %A. \n" ) ) ; 


Este  ejemplo  funciona  si  se  tienen  los  respectivos  ‘locales’  instalados  en  el  sistema. 
Ver  tambien  setlocale  ')  y  mktime  '). 


time 


(PHP  3,  PHP  4  >=  4.0.0) 


devuelve  el  timestamp  UNIX  actual 

int  time (void) ; 


Devuelve  la  hora  actual  como  numero  de  segundos  transcurridos  desde  las  00:00:00  del  1  de  enero  de 
1970  GMT  (Unix  Epoch). 
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Ver  tambien  date '). 
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XVII.  Funciones  para  dBase 

Estas  funciones  permiten  el  acceso  a  datos  almacenados  en  formato  dBase  (dbf). 

No  hay  soporte  para  indices  o  campos  Memo.  Tampoco  hay  soporte  para  bloqueo:  si  dos  procesos 
concurrentes  en  el  servidor  modifican  el  mismo  fichero  dBase,  probablemente  se  destruiran  los  datos. 

A  diferencia  de  las  bases  de  datos  SQL,  las  "bases  de  datos"  dBase  no  pueden  cambiar  su  definicion.  Una 
vez  creado  el  fichero,  la  definicion  de  la  base  de  datos  es  fija.  No  hay  indices  que  aceleren  la  busqueda  u 
organicen  los  datos  de  distinto  modo.  Los  ficheros  dBase  son  simples  ficheros  secuenciales  con  registros 
de  longitud  fija.  Los  nuevos  registros  se  anaden  al  final  del  fichero  y  los  registros  borrados  se  conservan 
hasta  que  se  llama  a  la  funcion  dbase_pack()(). 

Se  recomienda  no  utilizar  ficheros  dBase  como  bases  de  datos,  sino  elegir  cualquier  servidor  SQL; 
MySQL  o  Postgres  son  opciones  habituales  con  PHP.  El  soporte  para  dBase  se  proporciona  para  permitir 
importar  y  exportar  datos  a  y  desde  la  base  de  datos  web,  ya  que  este  formato  de  ficheros  es  aceptado 
habitualmente  por  las  hojas  de  datos  y  los  organizadores  de  Windows.  La  importacion  y  exportacion  de 
datos  es  lo  unico  para  lo  que  sirve  el  soporte  dBase. 
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dbase_create  (PHP3,  PHP  4  >=  4.0.0) 

crea  una  base  de  datos  dBase 


int  dbase_create  (string  filename,  array  fields) 


El  parametro  fields  es  un  array  de  arrays,  cada  uno  de  los  cuales  describe  el  formato  de  un  campo  de 
la  base  de  datos.  Cada  campo  consiste  de  un  nombre,  un  caracter  que  indica  el  tipo  de  campo,  una 
longitud,  y  una  precision. 

Los  tipos  de  campos  disponibles  son: 


L 


Logico.  No  tienen  longitud  ni  precision. 


M 

Memo.  (Sin  soporte  en  PHP.)  No  tienen  longitud  ni  precision. 


D 


Fecha  (almacenada  como  AAAAMMDD).  No  tienen  longitud  ni  precision. 


N 

Numero.  Tienen  longitud  y  precision  (numero  de  cifras  tras  el  punto  decimal). 


C 


Cadena. 


Si  la  base  de  datos  se  crea  con  exito,  se  devuelve  un  dbase_identifier;  en  caso  contrario,  devuelve  false. 


Ejemplo  1.  Crear  un  fichero  dBase 

//  "database"  name 
$dbname  =  " /tmp/test . dbf " ; 


//  database  "definition" 
$def  = 

array ( 

array ( "date" , 
array ( "name" , 
array ( "age " , 
array ( "email " , 
array ( " ismember " , 


"D")  , 

"C",  50), 

"N",  3,  0), 

"C",  128), 
"L") 


/ /  creation 
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if  ( ! dbase_create ($dbname,  $def) ) 

print  "<strong>Error ! </ strong>" ; 


dbase_open  (PHP  3,  PHP  4  >=  4.0.0) 

abre  un  fichero  dBase 

int  dbase_open  (string  filename,  int  flags) 

Los  "flags"  son  los  que  utiliza  la  llamada  al  sistema  open().  Normalmente,  0  significa  solo  lectura,  1  solo 
escritura  y  2  lectura  y  escritura. 

Devuelve  un  dbase_identifier  del  fichero  abierto,  o  false  si  no  pudo  abrirse  el  fichero. 

dbase_close  (PHP  3,  PHP  4  >=  4.0.0) 

cierra  un  fichero  dBase 

bool  dbase_close  (int  dbase_identifier) 

Cierra  el  fichero  asociado  con  dbase_identifier. 

dbase_pack  (PHP  3,  PHP  4  >=  4.0.0) 

"empaqueta"  un  fichero  dBase 

bool  dbase_pack  (int  dbase_identifier) 

Empaqueta  el  fichero  especificado,  borrando  definitivamente  todos  los  registros  marcados  con  la  funcion 
dbase_delete_record  ). 
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dbase_add_record  (php 3,  php 4 >=  4.o.o) 

anade  un  registro  a  un  fichero  dBase 

bool  dbase_add_record  (int  dbase_identifier,  array  record) 


Anade  los  datos  de  record  a  la  base  de  datos.  Si  el  numero  de  elementos  del  registro  proporcionado 
no  es  igual  al  numero  de  campos  de  la  base  de  datos,  la  operacion  fallara  y  la  funcion  devolvera  false. 


dbase_replace_record  (php  3>=  3.o.i  i ,  php  4  >=  4 .0  .o> 


reemplaza  un  registro  en  un  fichero  dBase 


bool  dbase_replace_record  (int  dbase_identifler,  array  record,  int 
dbase_record_number ) 


Reemplaza  los  datos  asociados  con  el  registro  record_number  con  los  datos  de  record  en  el  fichero 
de  datos.  Si  el  numero  de  elementos  del  registro  proporcionado  no  es  igual  al  numero  de  campos  de  la 
base  de  datos,  la  operacion  fallara  y  la  funcion  devolvera  false. 

dbase_record_number  es  un  entero  en  el  rango  de  1  al  numero  de  registros  en  el  fichero  de  datos 
(devuelto  por  la  funcion  dbase_numrecords ')). 


dbase_delete_record  (php 3  PHP 4 >=  4.0.o) 

borra  un  registro  del  fichero  dBase 

bool  dbase_delete_record  (int  dbase_identifier,  int  record ) 


Marca  el  registro  record  para  ser  borrado  del  fichero  de  datos.  Para  eliminar  realmente  el  registro  del 
fichero,  debe  llamarse  a  la  funcion  dbase_pack'). 


dbase_get_record  (php 3  PHP 4 >=  4.o.0) 

lee  un  registro  de  un  fichero  dBase 
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array  dbase_get_record  (int  dbase_identifier,  int  record) 


Devuelve  los  datos  del  registro  record  en  un  array.  El  array  se  indexa  a  partir  de  0,  e  incluye  un 
elemento  con  el  mdice  asociativo  ’deleted’,  que  vale  1  si  el  registro  ha  sido  marcado  para  borrar  (ver 
dbase_delete_record '). 

Cada  campo  se  convierte  al  tipo  PHP  apropiado.  (Las  fechas  se  guardan  como  cadenas.) 


dbase_get_record_with  names  (php 3>=  3.0.4,  php 4 >=  4.o.o) 

lee  un  registro  de  un  fichero  dBase  como  array  asociativo 

array  dbase_get_record_with_names  (int  dbase_identifier,  int  record ) 

Devuelve  los  datos  del  registro  record  en  un  array  asociativo.  El  array  incluye  tambien  un  elemento 
con  mdice  ’deleted’  que  vale  1  si  el  registro  ha  sido  marcado  para  borrar  (ver  dbase_delete_record'). 

Cada  campo  se  convierte  al  tipo  PHP  apropiado.  (Las  fechas  se  transforman  en  cadenas.) 


dbase_numf ields  (php 3  php 4 >=  4.0.o) 

cuenta  el  numero  de  campos  en  un  fichero  dBase 

int  dbase_numf ields  (int  dbase_identifier) 


Devuelve  el  numero  de  campos  (columnas)  en  el  fichero  especificado.  Los  numeros  de  campo  va  de  0  a 
dbase_numfields($db)-l,  mientras  los  numeros  de  registros  van  de  1  a  dbase_numrecords($db). 

Ejemplo  1.  Uso  de  dbase_numfields() 

$rec  =  dbase_get_record ( $db,  $recno) ; 

$nf  =  dbase_numf ields ($db) ; 
for  ($i=0 ;  $i  <  $nf;  $i++)  { 

print  $rec[$i] . "<br>\n"; 

} 
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dbase_numrecords  (php  3,  PHP  4  >=  4.0.0 

cuenta  el  numero  de  registros  en  un  fichero  dBase 

int  dbase_numrecords  (int  dbase_identifier) 


Devuelve  el  numero  de  registros  (filas)  en  el  fichero  especificado.  Los  numeros  de  registro  van  de  1  a 
dbase_numrecords($db),  mientras  los  numeros  de  campo  van  de  0  a  dbase_numfields($db)-l. 
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Estas  funcione  le  permiten  almacenar  registros  en  una  base  de  datos  estilo  dbm.  Este  tipo  de  base  de 
datos  (soportadas  por  las  librerfas  db  y  gdbm  de  Berkeley,  asf  como  por  algunas  librerfas  del  sistema  y 
por  una  librerfa  inclufda  para  acceso  a  archivos  de  texto)  guarda  pares  clave/valor  (en  oposicion  a  los 
registros  completos  soportados  por  las  bases  de  datos  relacionales). 


Ejemplo  1.  ejemplo  de  dbm 

$dbm  =  dbmopen ( "vistoya" ,  "w"); 

if  (dbmexists ( $dbm,  $idusuario) )  { 

$visto_ya  =  dbmfetch ( $dbm,  $idusuario) ; 
}  else  { 

dbminsert  ($dbm,  $idusuario,  timed); 

} 

do_stuf f ( )  ; 

dbmreplace  ( $dbm,  $idusuario,  timed); 
dbmclose ($dbm) ; 
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DBM 


abre  una  base  de  datos  dbm 


int  dbmopen  (string  fichero,  string  indicadores) 


El  primer  argumento  es  el  nombre  con  sendero  completo  del  archivo  dbm  que  se  va  a  abrir  y  el  segundo 
es  el  modo  de  apertura,  que  puede  ser  "r",  "n",  "c"  o  "w",  que  significan  solo  lectura,  nuevo  (implica 
lectura/escritura  y  suele  truncar  una  base  de  datos  si  ya  existfa  con  ese  nombre),  crear  (implica 
lectura/escritura,  pero  sin  truncar  la  base  de  datos)  y  abrir  para  lectura/escritura,  respectivamente. 

Devuelve  un  identificador  que  se  pasa  al  resto  de  funciones  dbm  si  tiene  exito,  o  false  si  falla. 

Si  se  utiliza  el  soporte  de  ndbm,  este  creara  los  archivos  fichero. dir  y  fichero.pag.  gdbm  solo  utiliza  un 
archivo  y  lo  mismo  hace  el  soporte  interno  de  archivos  de  texto,  mientras  que  el  db  de  Berkeley  crea  un 
archivo  fichero. db.  Notese  que  el  PHP  hace  su  propio  bloqueo  de  archivo  sobre  el  que  pudiera  realizar  la 
propia  librerfa  dbm.  El  PHP  no  borra  los  archivos  .lck  que  crea.  Los  utiliza  simplemente  como  i-nodos 
fijos  en  los  que  hacer  el  bloqueo.  Para  mas  informacion  sobre  archivos  dbm,  vea  las  paginas  man  de  su 
Unix  o  obtenga  el  gdbm  de  GNU  desde  ftp  :  /  /prep  .  ai  .mit .  edu/pub/gnu. 


dbmclose  (PHP  3,  PHP  4  >=  4.0.0) 
cierra  una  base  de  datos  dbm 


bool  dbmclose  (int  identif_dbm) 


Desbloquea  y  cierra  la  base  de  datos  especificada. 


dbmexists  (PHP  3,  PHP  4  >=4.0.0) 

dice  si  existe  un  valor  para  una  clave  dada  en  la  base  de  datos  dbm 

bool  dbmexists  (int  identif_dbm,  string  clave) 


Devuelve  true  si  hay  un  valor  asociado  con  la  clave. 
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dbmfetch  (PHP  3,  PHP  4  >=  4.0.0) 

obtiene  un  valor  para  una  clave  desde  la  base  de  datos  dbm 

string  dbmfetch  (int  identif_dbm,  string  clave) 

Devuelve  el  valor  asociado  con  la  clave. 

dbminsert  (PHP  3,  PHP  4  >=  4.0.0) 

inserta  un  valor  para  una  clave  en  la  base  de  datos  dbm 

int  dbminsert  (int  identif_dbm,  string  clave,  string  valor) 

Anade  el  valor  a  la  base  de  datos  con  la  clave  especificada. 

Devuelve  -1  si  la  base  de  datos  se  abrfo  en  modo  solo  lectura,  0  si  la  insercion  tuvo  exito  y  1  si  la  clave 
ya  existfa  (para  sustituir  el  valor,  utilice  dbmreplace').) 

dbmreplace  (PHP  3,  PHP  4  >=4.0.0) 

sustituye  el  valor  de  una  clave  en  la  base  de  datos  dbm 

bool  dbmreplace  (int  ldentif_dbm,  string  clave,  string  valor) 

Sustituye  el  valor  para  la  clave  especificada  de  la  base  de  datos. 

Tambien  anadira  la  clave  a  la  base  de  datos  si  no  existfa  antes. 

dbmdelete  (PHP  3,  PHP  4  >=4.0.0) 

borra  el  valor  de  una  clave  de  una  base  de  datos  dbm 

bool  dbmdelete  (int  identif_dbm,  string  clave) 
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Borra  el  valor  para  la  clave  en  la  base  de  datos. 
Devuelve  false  si  la  clave  no  existfa  en  la  base  de  datos. 
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dbmf irstkey  (php 3,  php 4 >=  4.0.0) 

obtiene  la  primera  clave  de  una  base  de  datos  dbm 

string  dbmfirstkey  (int  identif_dbm) 


Devuelve  la  primera  clave  de  la  base  de  datos.  Notese  que  no  se  garantiza  ningun  orden  en  particular, 
pues  la  base  de  datos  se  crea  utilizando  una  tabla  hash,  que  no  garantiza  ordenacion  alguna. 


dbmnextkey  (php 3,  php 4 >=  4.o.0) 

obtiene  la  siguiente  clave  de  una  base  de  datos  dbm 

string  dbmnextkey  (int  identif_dbm,  string  clave) 


Devuelve  la  clave  que  sigue  a  clave.  Llamando  a  dbmfirstkey')  seguida  de  llamadas  sucesivas  a 
dbmnextkeyO  se  pueden  visitar  todos  los  pares  clave/valor  de  la  base  de  datos  dbm.  Por  ejemplo: 

Ejemplo  1.  Visitanco  cada  par  clave/valor  en  una  base  de  datos  dbm. 

$clave  =  dbmfirstkey ($id_dbm) ; 
while  ($clave)  { 

echo  "$clave  =  "  .  dbmfetch ($id_dbm,  $clave)  .  "\n"; 

$clave  =  dbmnextkey ($id_dbm,  $clave) ; 

} 


dblist  (PHP  3,  PHP  4  >=4.0.0) 


describe  la  librerfa  compatible  dbm  que  se  esta  usando 


string  dblist  (void) 


261 


DBM 


262 


XIX.  dbx  functions 


Aviso 

This  module  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  these 
functions,  these  function  names,  in  concreto  ANYTHING  documented  here  can 
change  in  a  future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this 
module  at  your  own  risk. 


The  dbx  module  is  a  database  abstraction  layer  (db  ’X’,  where  ’X’  is  a  supported  database).  The  dbx 
functions  allow  you  to  access  all  supported  databases  using  a  single  calling  convention.  In  order  to  have 
these  functions  available,  you  must  compile  PHP  with  dbx  support  by  using  the  — enable-dbx  option 
and  all  options  for  the  databases  that  will  be  used,  e.g.  for  MySQL  you  must  also  specify 
— with-mysql.  The  dbx-functions  themselves  do  not  interface  directly  to  the  databases,  but  interface  to 
the  modules  that  are  used  to  support  these  databases.  To  be  able  to  use  a  database  with  the  dbx-module, 
the  module  must  be  either  linked  or  loaded  into  PHP,  and  the  database  module  must  be  supported  by  the 
dbx-module.  Currently,  MySQL,  PostgreSQL,  Microsoft  SQL  Server,  FrontBase  and  ODBC  are 
supported,  but  others  will  follow  (soon,  I  hope 

Documentation  for  adding  additional  database  support  to  dbx  can  be  found  at 
http://www.guidance.nl/php/dbx/doc/. 
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dbx_close  (PHP  4  >=  4.0.6) 

Close  an  open  connection/database 

bool  dbx_close  (dbx_link_ob ject  link_identifier) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


Returns  true  on  success,  false  on  error. 

Ejemplo  1.  dbx_close()  example 

<?php 

$link  =  dbx_connect  ("mysql",  "localhost",  "db",  "username",  "password") 
or  die  ("Could  not  connect"); 
print ("Connected  successfully") ; 
dbx_close ($link) ; 

?> 


Nota:  Always  refer  to  the  module-specific  documentation  as  well. 


See  also:  dbx_connecC). 


dbxconnect  (php  4  >=  4  o  6> 


Open  a  connection/database 


dbx_link_ob ject  dbx_connect  (string  module,  string  host,  string  database , 
string  username,  string  password  [,  int  persistent ]) 
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Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


Returns:  a  dbx_link_object  on  success,  false  on  error.  If  a  connection  has  been  made  but  the  database 
could  not  be  selected,  the  connection  is  closed  and  false  is  returned.  The  ’persistent’  parameter  can  be 
set  to  DBX_PERSISTENT  so  a  persistent  connection  will  be  created. 

The  module  parameter  can  be  either  a  string  or  a  constant.  The  possible  values  are  given  below,  but 
keep  in  mind  that  they  only  work  if  the  module  is  actually  loaded. 


•  module  DBX_MYSQL  :  "mysql" 

•  module  DBX_ODBC  :  "odbc" 

•  module  DBX_PGSQL  :  "pgsql" 

•  module  DBX_MSSQL  :  "mssql” 

•  module  DBX_FBSQL  :  "fbsql"  (CVS  only) 


The  dbx_link_object  has  three  members,  a  ’handle’,  a  ’module’  and  a  ’database’.  The  ’database’  member 
is  the  name  of  the  currently  selected  database.  The  ’module’  member  is  for  internal  use  by  dbx  only,  and 
is  actually  the  module  number  mentioned  above.  The  ’handle’  member  is  a  valid  handle  for  the 
connected  database,  and  as  such  can  be  used  in  module-specific  functions  (if  required),  e.g. 


<?php 

$link  =  dbx_connect  ("mysql",  "localhost",  "db",  "username",  "password"); 
mysql_close  ($link->handle) ;  //  dbx_close ($link)  would  be  better  here 
?> 


Host,  database,  username  and  password  parameters  are  expected,  but  not  always  used,  depending  on  the 
connect-functions  for  the  abstracted  module. 


Ejemplo  1.  dbx_connect()  example 


<?php 

$link  =  dbx_connect  ("odbc",  "db", 

or  die  ("Could  not  connect") ; 
print  ("Connected  successfully"); 
dbx_close  ($link) ; 

?> 


"username " , 


"password",  DBX_PERSISTENT ) 
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Nota:  Always  refer  to  the  module-specific  documentation  as  well. 


See  also:  dbx_close(). 


dbx_error(PHP4>=4  0  6) 

Report  the  error  message  of  the  latest  function  call  in  the  module  (not  just  in  the  connection) 

string  dbx_error  (dbx_link_ob ject  link_identifier) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


Returns  a  string  containing  the  error-message  from  the  last  function  call  of  the  module  (e.g. 
mysql-module).  If  there  are  multiple  connections  on  the  same  module,  just  the  last  error  is  given.  If  there 
are  connections  on  different  modules,  the  latest  error  is  returned  for  the  specified  module  (specified  by 
the  link  parameter,  that  is).  Note  that  the  ODBC-module  doesn’t  support  an  error_reporting  function  at 
the  moment. 

Ejemplo  1.  dbx_error()  example 

<?php 

$link  =  dbx_connect  ("mysql",  "localhost",  "db",  "username",  "password") 
or  die  ("Could  not  connect"); 

$result  =  dbx_query  ($link,  "select  id  from  nonexistingtbl" ) ; 
if  ($result==0)  { 

echo  dbx_error  ($link); 

} 

dbx_close  ($link); 

?> 


Nota:  Always  refer  to  the  module-specific  documentation  as  well. 

The  error-message  for  Microsoft  SQL  Server  is  actually  the  result  of  the 

mssql_get_last_message()  function. 
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dbx_query  (php4>=4  0  6) 


Send  a  query  and  fetch  all  results  (if  any) 


dbx_result_ob ject  dbx_query  (dbx_link_ob ject  link_identifier ,  string 
sql_statement  [,  long  flags]) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


Returns  a  dbx_result_object  or  1  on  success  (a  result  object  is  only  returned  for  sql-statements  that  return 
results)  or  0  on  failure.  The  flags  parameter  is  used  to  control  the  amount  of  information  that  is 
returned.  It  may  be  any  combination  of  the  constants  DBX_RESULT_INFO,  DBX_RESULT_INDEX, 
DBX_RESULT_ASSOC,  OR-ed  together.  DBX_RESULT_INFO  provides  info  about  columns,  such  as 
field  names  and  field  types.  DBX_RESULT_INDEX  returns  the  results  in  a  2d  indexed  array  (e.g. 
data[2][3],  where  2  is  the  row  (or  record)  number  and  3  is  the  column  (or  field)  number),  where  the  first 
row  and  column  are  indexed  at  0.  DBX_RESULT_ASSOC  associates  the  column  indices  with  field 
names.  Note  that  DBX_RESULT_INDEX  is  always  returned,  regardless  of  the  flags  parameter.  If 
DBX_RESULT_ASSOC  is  specified,  DBX_RESULT_INFO  is  also  returned  even  if  it  wasn’t  specified. 
This  means  that  effectively  only  the  combinations  DBX_RESULT_INDEX,  DBX_RESULT_INDEX  I 
DBX_RESULT_INFO  and  DBX_RESULT_INDEX  I  DBX_RFSULT_INFO  I  DBX_RESULT_ASSOC 
are  possible.  This  last  combination  is  the  default  if  the  flags  parameter  isn’t  specified.  Associated 
results  are  actual  references  to  the  indexed  data,  so  if  you  modify  data  [  0  ]  [  0  ] ,  then 
data[0]  [ '  f ieldnamef orf irstcolumn'  ]  is  modified  as  well. 

A  dbx_result_object  has  five  members  (possibly  four  depending  on  flags),  ’handle’,  ’cols’,  ’rows’, 
’info’  (optional)  and  ’data’.  Handle  is  a  valid  result  identifier  for  the  specified  module,  and  as  such  can  be 
used  in  module-specific  functions,  as  seen  in  the  example: 

$result  =  dbx_query  ($link,  "SELECT  id  FROM  tbl"); 
mysql_f ield_len  ($result->handle,  0); 


The  cols  and  rows  members  contain  the  number  of  columns  (or  fields)  and  rows  (or  records)  respectively, 
e.g. 

$result  =  dbx_query  ($link,  "SELECT  id  FROM  tbl"); 

echo  "result  size:  "  .  $result->rows  .  "  x  "  .  $result->cols  .  "<br>\n"; 
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The  info  member  is  only  returned  if  DBX_RESULT_INFO  and/or  DBX_RESULT_ASSOC  are  specified 
in  the  flags  parameter.  It  is  a  2d  array,  that  has  two  named  rows  ("name"  and  "type")  to  retrieve 
column  information,  e.g. 

$result  =  dbx_query  ($link,  "SELECT  id  FROM  tbl"); 

echo  "column  name:  "  .  $result->info [ "name" ] [0]  .  "<br>\n"; 

echo  "column  type:  "  .  $result->inf o [ "type " ]  [0]  .  "<br>\n"; 


The  data  member  contains  the  actual  resulting  data,  possibly  associated  with  column  names  as  well.  If 
DBX_RESULT_ASSOC  is  set,  it  is  possible  to  use  $result->data  [2  ]  [ " fieldname"  ] . 

Ejemplo  1.  dbx_query()  example 

<?php 

$link  =  dbx_connect  ("odbc",  "db",  "username",  "password") 

or  die  ("Could  not  connect"); 

$result  =  dbx_query  ($link,  "SELECT  id,  parentid,  description  FROM  tbl"); 
if  ($result==0)  echo  "Query  failed\n<br>" ; 
elseif  ($result==l)  { 

echo  "Query  executed  successfully\n<br>" ; 

}  else  { 

$rows=$result->rows ; 

$cols=$result->cols; 

echo  "<p>table  dimension:  { $result->rows }  x  { $result->cols } <br><table  bor- 
der=l>\n" ; 

echo  "<tr>"; 

for  ($col=0;  $col<$cols;  ++$col)  { 

echo  "<td>- { $result->info [ "name" ] [$col] } -<br>- { $result->inf o [ "type " ] [$col] }- 

</td>" ; 

} 

echo  "</tr>\n"; 

for  ($row=0;  $row<$rows;  ++$row) { 
echo  "<tr>"; 

for  ($col=0;  $col<$cols;  ++$col)  { 

echo  "<td>- { $result->data [ $row] [ $col ] } -</td>" ; 

} 

echo  "</tr>\n"; 

} 

echo  "</table><p>\n" ; 

echo  "table  dimension:  { $result->rows }  x  id,  parentid,  description<br><table  bor- 
der=l>\n" ; 

for  ($row=0;  $row<$rows;  ++$row)  { 

echo  "<tr>"; 

echo  " <td>- { $result->data [ $row] [ "id" ] }-</td>" ; 
echo  "<td>- { $result->data [ $row] [ "parentid" ]} -</td>" ; 
echo  "<td>- { $result->data [ $row] [ "description" ]} -</td>" ; 
echo  "</tr>\n"; 

} 

echo  "</tablexp>\n"  ; 
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} 

dbx_close ($link) ; 
?> 
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Nota:  Always  refer  to  the  module-specific  documentation  as  well. 


See  also:  dbx_connect3. 


dbxsort  (php  4  >=  4.0.6) 

Sort  a  result  from  a  dbx_query  by  a  custom  sort  function 

bool  dbx_sort  (dbx_result_ob ject  result,  string  user_compare_f unction) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


Returns  true  on  success,  false  on  error. 

Ejemplo  1.  dbx_sort()  example 

<?php 

function  user_re_order  ($a,  $b)  { 

$rv  =  dbx_compare  ($a,  $b,  "parentid",  DBX_CMP_DESC) ; 
if  (!$rv)  $rv  =  dbx_compare  ($a,  $b,  "id"); 

return  $rv; 

} 

$link  =  dbx_connect  ("odbc",  "db",  "username",  "password") 

or  die  ("Could  not  connect"); 

$result  =  dbx_query  ($link,  "SELECT  id,  parentid,  description  FROM  tbl  ORDER  BY  id" 

echo  "resulting  data  is  now  ordered  by  id<br>"; 

dbx_sort  ($result,  "user_re_order " ) ; 

echo  "resulting  data  is  now  ordered  by  parentid  (descending),  then  by  id<br>"; 

dbx_close  (Slink) ; 

?> 


See  also  dbx_compareO. 
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dbxcompare  (php  4  >=  4 .0 .7rci) 


Compare  two  rows  for  sorting  purposes 


int  dbx_compare  (array  row_a,  array  row_b,  string  columnname_or_index  [,  int 
flags] ) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


Returns  0  if  row_a[$columnname_or_index]  is  equal  to  row_b[$columnname_or_index],  1  if  it  is  greater 
and  -1  if  it  is  smaller  (or  vice  versa  if  the  DBX_CMP_DESC  flag  is  set). 

The  flags  can  be  set  to  specify  comparison  direction  (whether  sorting  is  ascending  or  descending)  and 
comparison  type  (force  string  or  numeric  compare  by  converting  the  data).  The  constants  for  direction  are 
DBX_CMP_ASC  and  DBX_CMP_DESC.  The  constants  for  comparison  type  are  DBX_CMP_NATIVE 
(no  conversion),  DBX_CMP_TEXT  and  DBX_CMP_NUMBER.  These  constants  can  be  OR-ed 
together.  The  default  value  for  the  flags  parameter  is  DBX_CMP_ASC  I  DBX_CMP_NATIVE. 

Ejemplo  1.  dbx_compare()  example 


<?php 

function  user_re_order  ($a,  $b)  { 

$rv  =  dbx_compare  ($a,  $b,  "parentid",  DBX_CMP_DESC) ; 
if  ( ! $rv)  { 

$rv  =  dbx_compare  ($a,  $b,  "id"); 

return  $rv; 

} 

} 

$link  =  dbx_connect  ("odbc",  "db",  "username",  "password") 

or  die  ("Could  not  connect"); 

$result  =  dbx_query  ($link,  "SELECT  id,  parentid,  description  FROM  tbl  ORDER  BY  id" 
echo  "resulting  data  is  now  ordered  by  id<br>"; 
dbx_sort  ($result,  "user_re_order " ) ; 

echo  "resulting  data  is  now  ordered  by  parentid  (descending),  then  by  id<br>"; 
dbx_close  ($link); 

?> 


See  also  dbx_sort'). 
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Aviso 

This  module  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  these 
functions,  these  function  names,  in  concreto  ANYTHING  documented  here  can 
change  in  a  future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this 
module  at  your  own  risk. 


DB++  Database  Functions 


db++,  made  by  the  german  company  Concept  asa  (http://www.concept-asa.de/),  is  a  relational  database 
system  with  high  performance  and  low  memory  and  disk  usage  in  mind.  While  providing  SQL  as  an 
additional  language  interface  it  is  not  really  a  SQL  database  in  the  first  place  but  provides  its  own  AQL 
query  language  which  is  much  more  influenced  by  the  relational  algebra  then  SQL  is. 

Concept  asa  always  had  an  interest  in  supporting  open  source  languages,  db++  has  had  Perl  and  Tel  call 
interfaces  for  years  now  and  uses  Tel  as  its  internal  stored  procedure  language. 


Requirements 

You  need  the  developement  libraries  and  header  files  included  in  every  db++  installaion  archive.  Concept 
asa  (http://www.concept-asa.de/)  provides  additional  documentation 
(http://www.concept-asa.de/downloads/doc-eng.tar.gz)  and  Demo  versions 
(http://www.concept-asa.de/down-eng.html)  of  db++  for  Linux,  some  other  UNIX  versions  and 
Windows95/NT. 


Installation 


Creation  and  installation  of  this  extension  requires  the  db++  client  libraries  and  header  files  to  be 
installed  on  your  system.  You  have  to  run  configure  with  option  — with-dbplus  to  build  this  extension. 

configure  looks  for  the  client  libraries  and  header  files  under  the  default  pathes  /usr/dbplus, 
/usr/local/dbplus  and  /opt/dblus.  If  you  have  installed  db++  in  a  different  place  you  have  add 
the  installation  path  to  the  configure  option  like  this:  — with-dbplus=/your/installation/path. 


db++  error  codes 


Tabla  1.  DB++  Error  Codes 


PHP  Constant 


db++  constant 


meaning 
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PHP  Constant 

db++  constant 

meaning 

DBPLUS ERR NOERR 

ERR NOERR 

Null  error  condition 

DBPLUS ERR DUPLICATE 

ERR D  UPLIC  ATE 

Tried  to  insert  a  duplicate  tuple 

DBPLUS ERR EOSCAN 

ERR EOSCAN 

End  of  scan  from  rget() 

dbplus err empty 

err empty 

Relation  is  empty  (server) 

DBPLUS ERR CLOSE 

ERR CLOSE 

The  server  can’t  close 

DBPLUS ERR WLOCKED 

ERR WLOCKED 

The  record  is  write  locked 

DBPLUS ERR LOCKED 

ERR LOCKED 

Relation  was  already  locked 

DBPLUS ERR NOLOCK 

ERR NOLOCK 

Relation  cannot  be  locked 

dbplus err read 

ERR READ 

Read  error  on  relation 

DBPLUS ERR WRITE 

ERR WRITE 

Write  error  on  relation 

DBPLUS ERR CREATE 

ERR CREATE 

Create()  system  call  failed 

DBPLUS ERR LSEEK 

ERR LSEEK 

LseekQ  system  call  failed 

DBPLUS ERR LENGTH 

ERR LENGTH 

Tuple  exceeds  maximum  length 

DBPLUS ERR OPEN 

ERR OPEN 

Open()  system  call  failed 

DBPLUS_ERR_WOPEN 

ERR_WOPEN 

Relation  already  opened  for 
writing 

DBPLUS ERR MAGIC 

ERR MAGIC 

File  is  not  a  relation 

DBPLUS ERR VERSION 

ERR VERSION 

File  is  a  very  old  relation 

DBPLUS ERR PGSIZE 

ERR PGSIZE 

Relation  uses  a  different  page  size 

DBPLUS ERR CRC 

ERR CRC 

Invalid  crc  in  the  superpage 

DBPLUS ERR PIPE 

ERR PIPE 

Piped  relation  requires  lseek() 

DBPLUS ERR NIDX 

ERR NIDX 

Too  many  secondary  indices 

DBPLUS ERR MALLOC 

ERR MALLOC 

Malloc()  call  failed 

DBPLUS ERR NUSERS 

ERR NUSERS 

Error  use  of  max  users 

DBPLUS ERR PREEXIT 

ERR PREEXIT 

Caused  by  invalid  usage 

DBPLUS ERR ONTRAP 

ERR ONTRAP 

Caused  by  a  signal 

DBPLUS ERR PREPROC 

ERR PREPROC 

Error  in  the  preprocessor 

DBPLUS ERR DBPARSE 

ERR DBPARSE 

Error  in  the  parser 

DBPLUS ERR DBRUNERR 

ERR DBRUNERR 

Run  error  in  db 

DBPLUS_ERR_DBPREEXIT 

ERR_DBPREEXIT 

Exit  condition  caused  by  prexit()  * 
procedure 

DBPLUS ERR WAIT 

ERR WAIT 

Wait  a  little  (Simple  only) 

DBPLUS_ERR_CORRUPT_TUPI 

EERR_CORRUPT_TUPLE 

A  client  sent  a  corrupt  tuple 

DBPLUS_ERR_WARNINGO 

ERR_WARNINGO 

The  Simple  routines  encountered 
a  non  fatal  error  which  was 

corrected 

DBPLUS_ERR_PANIC 

ERR_PANIC 

The  server  should  not  really  die 
but  after  a  disaster  send 
ERR_PANIC  to  all  its  clients 
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PHP  Constant 

db++  constant 

meaning 

DBPLUS ERR FIFO 

ERR FIFO 

Can’t  create  a  fifo 

DBPFUS ERR PERM 

ERR PERM 

Permission  denied 

DBPLUS ERR TCL 

ERR TCL 

TCL error 

DBPLUS ERR RESTRICTED 

ERR RESTRICTED 

Only  two  users 

DBPLUS_ERR_USER 

ERR_USER 

An  error  in  the  use  of  the  library 
by  an  application  programmer 

DBPLUS_ERR_UNKNOWN 

ERR_UNKNOWN 
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DB++ 


Add  a  tuple  to  a  relation 


int  dbplus_add  (resource  relation,  array  tuple) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


This  function  will  add  a  tuple  to  a  relation.  The  tuple  data  is  an  array  of  attribute/value  pairs  to  be 
inserted  into  the  given  relation.  After  successfull  execution  the  tuple  array  will  contain  the 
complete  data  of  the  newly  created  tuple,  including  all  implicitly  set  domain  fields  like  sequences. 

The  function  will  return  zero  (aka.  DBPLUS_ERR_NOERR)  on  success  or  a  db++  error  code  on  failure. 
See  dbplus_errcode ')  or  the  introduction  to  this  chapter  for  more  information  on  db++  error  codes. 


dbplus_aql  (PHP  4  >=  4.0.7RC1) 


Perform  AQL  query 


resource  dbplus_aql  (string  query  [,  string  server  [,  string  dbpath ]]) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


dbplus_aql()  will  execute  an  AQL  query  on  the  given  server  and  dbpath. 

On  success  it  will  return  a  relation  handle.  The  result  data  may  be  fetched  from  this  relation  by  calling 
dbplus_next ')  and  dbplus_current().  Other  relation  access  functions  will  not  work  on  a  result  relation. 

Further  information  on  the  AQL  A...  Query  Language  is  provided  in  the  opriginal  db++  manual. 
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dbplus_chdir  (php  4  >=  4.o.7rci) 

Get/Set  database  virtual  current  directory 

string  dbplus_chdir  ([string  newdir]) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


dbplus_chdir()  will  change  the  virtual  current  directory  where  relation  files  will  be  looked  for  by 
dbplus_open ').  dbplus_chdir()  will  return  the  absolute  path  of  the  current  directory.  Calling 
dbplus_chdir()  without  giving  any  newdir  may  be  used  to  query  the  current  working  directory. 


dbplus_close  (PHP  4  >=  4.0.7RC1) 


Close  a  relation 


int  dbplus_close  (resource  relation) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


Calling  dbplus_close()  will  close  a  relation  previously  opened  by  dbplus_openO- 


dbplus_curr  (php  4  >=  4.o.7rci) 


Get  current  tuple  from  relation 


int  dbplus_curr  (resource  relation, 


array  tuple) 
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Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


dbplus_curr()  will  read  the  data  for  the  current  tuple  for  the  given  relation  and  will  pass  it  back  as 
an  associative  array  in  tuple. 

The  function  will  return  zero  (aka.  DBPLUS_ERR_NOERR)  on  success  or  a  db++  error  code  on  failure. 
See  dbplus_errcode ')  or  the  introduction  to  this  chapter  for  more  information  on  db++  error  codes. 

See  also  dbplus_firstO,  dbplus_prev '),  dbplus_next'),  and  dbplus_last'). 


dbplus_errcode  <php  4  >=  4.o.7rci) 

Get  error  string  for  given  errorcode  or  last  error 

string  dbplus_errcode  (int  errno) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


dbplus_errcode()  returns  a  cleartext  error  string  for  the  error  code  passed  as  errno  of  for  the  result 
code  of  the  last  db++  operation  if  no  parameter  is  given. 


dbplus_errno  <php  4  >=  4.o.7rci) 


Get  error  code  for  last  operation 


int  dbplus_errno  () 
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Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


dbpIus_errno()  will  return  the  error  code  returned  by  the  last  db++  operation. 
See  also  dbplus_errcode'j. 


dbplus_find  (php4>=4.o.7rci) 


Set  a  constraint  on  a  relation 


int  dbplus_find  (resource  relation,  array  constraints ,  mixed  tuple) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


dbplus_find()  will  place  a  constraint  on  the  given  relation.  Further  calls  to  functions  like  dbplus_curr() 
or  dbplus  next  )  will  only  return  tuples  matching  the  given  constraints. 

Constraints  are  triplets  of  strings  containing  of  a  domain  name,  a  comparison  operator  and  a  comparison 
value.  The  constraints  parameter  array  may  consist  of  a  collection  of  string  arrays,  each  of  which 
contains  a  domain,  an  operator  and  a  value,  or  of  a  single  string  array  containing  a  multiple  of  three 
elements. 

The  comparison  operator  may  be  one  of  the  following  strings:  ’==’,  ’>’,  ’>=',  ’<’,  ’<=’,  ’  !=’,  for  a 
regular  expression  match  and  ’BAND’  or  ’BOR’  for  bitwise  operations. 

See  also  dbplus_unselect(). 


dbplus_f  irst  (php  4  >=  4 .0  .trcij 


Get  first  tuple  from  relation 


int  dbplus_first  (resource  relation,  array  tuple) 
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Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


dbplus_curr')  will  read  the  data  for  the  first  tuple  for  the  given  relation,  make  it  the  current  tuple  and 
pass  it  back  as  an  associative  array  in  tuple. 

The  function  will  return  zero  (aka.  DBPLUS_ERR_NOERR)  on  success  or  a  db++  error  code  on  failure. 
See  dbplus_errcode ')  or  the  introduction  to  this  chapter  for  more  information  on  db++  error  codes. 

See  also  dbplus_curr'),  dbplus_prev '),  dbplus_next  [),  and  dbplus_last'j. 


dbplus  f  lush  (PHP  4  >=  4.0.7RC1 ) 


Flush  all  changes  made  on  a  relation 


int  dbplus_flush  (resource  relation) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


dbplus_liush()  will  write  all  changes  applied  to  relation  since  the  last  flush  to  disk. 

The  function  will  return  zero  (aka.  DBPLUS_ERR_NOERR)  on  success  or  a  db++  error  code  on  failure. 
See  dbplus_errcode ')  or  the  introduction  to  this  chapter  for  more  information  on  db++  error  codes. 


dbplus_f  reealllocks  (php  4  >=  4  0  7rcd 


Free  all  locks  held  by  this  client 


int  dbplus_freealllocks  () 
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Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


dbpIus_freeaalllocks()  will  free  all  tuple  locks  held  by  this  client. 

See  also  dbplus_getlock '),  dbplus_frcelock  ),  and  dbplus_freerlocks'). 


dbplus_f  reelock  (php  4  >=  4.o.7rci) 


Release  write  lock  on  tuple 


int  dbplus_freelock  (resource  relation,  string  tname) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


dbplus_freelock()  will  release  a  write  lock  on  the  given  t  upl  e  previously  obtained  by 

dbplus_getlock). 

See  also  dbplus_getlock '),  dbplus_freerlocks '),  and  d b p I u s_f reea blocks'). 


dbplus_f  reerlocks  (php  4  >=  4.0.7rci) 


Free  all  tuple  locks  on  given  relation 


int  dbplus_freerlocks  (resource  relation ) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 
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dbplus_freerlocks()  will  free  all  tuple  locks  held  on  the  given  relation. 
See  also  dbplus_getlock),  dbplus_freelock'),  and  dbplus_freealllocl<s '). 
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dbplus_getlock  (php  4  >=  4.o.7rcd 


Get  a  write  lock  on  a  tuple 


int  dbplus_getlock  (resource  relation,  string  tname) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


dbplus_getlock()  will  request  a  write  lock  on  the  speified  tuple.  It  will  return  zero  on  success  or  a 
non-zero  error  code,  especially  DBPLUS_ERR_WLOCKED,  on  failure. 

See  also  dbplus_frcelock '),  dbplus_freerlocksO,  and  dbplus_freealllocks  '). 


dbplus_getunique  (php  4  >=  4 .0  jrcu 


Get  a  id  number  unique  to  a  relation 


int  dbplus_getunique  (resource  relation,  int  uniqueid) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


dbplus_getunique()  will  obtain  a  number  guaranteed  to  be  unique  for  the  given  relation  and  will 
pass  it  back  in  the  variable  given  as  uniqueid. 

The  function  will  return  zero  (aka.  DBPLUS_ERR_NOERR)  on  success  or  a  db++  error  code  on  failure. 
See  dbplus_errcode ')  or  the  introduction  to  this  chapter  for  more  information  on  db++  error  codes. 
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??? 


int  dbplus_info  (resource  relation,  string  key,  array  ) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


Not  implemented  yet. 


dbplusjast  (PHP  4  >=  4.0.7RC1) 


Get  last  tuple  from  relation 


int  dbplus_last 


(resource  relation, 


array  tuple) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


dbplus_curr()  will  read  the  data  for  the  last  tuple  for  the  given  relation,  make  it  the  current  tuple  and 
pass  it  back  as  an  associative  array  in  tuple. 

The  function  will  return  zero  (aka.  DBPLUS_ERR_NOERR)  on  success  or  a  db++  error  code  on  failure. 
See  dbplus_errcode ')  or  the  introduction  to  this  chapter  for  more  information  on  db++  error  codes. 

See  also  dbplus_hrst'),  dbplus_curr'j,  dbplus_prev(j,  and  dbplus_next'). 


dbplusjockrel  (unknown) 


Request  write  lock  on  relation 
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int  dbplus_lockrel  (resource  relation) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


dbplus_lockrel()  will  request  a  write  lock  on  the  given  relation.  Other  clients  may  still  query  the 
relation,  but  can’t  alter  it  while  it  is  locked. 


dbplus_next  (php  4  >=  4 .0  .trcij 


Get  next  tuple  from  relation 


int  dbplus_next  (resource  relation,  array  ) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


dbplus_currO  will  read  the  data  for  the  next  tuple  for  the  given  relation,  will  make  it  the  current  tuple 
and  will  pass  it  back  as  an  associative  array  in  t  upl  e. 

The  function  will  return  zero  (aka.  DBPLUS_ERR_NOERR)  on  success  or  a  db++  error  code  on  failure. 
See  dbplus_errcode ')  or  the  introduction  to  this  chapter  for  more  information  on  db++  error  codes. 

See  also  dbplus_firstO,  dbplus_curr\),  dbplus_prev'),  and  dbplus_lastO- 


dbplus_open  (php  4  >=  4 .0  jrcu 


Open  relation  file 


resource  dbplus_open  (string  name) 
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Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


The  relation  file  name  will  be  opened,  name  can  be  either  a  file  name  or  a  relative  or  absolute  path  name. 
This  will  be  mapped  in  any  case  to  an  absolute  relation  file  path  on  a  specific  host  machine  and  server. 

On  success  a  relation  file  resource  (cursor)  is  returned  which  must  be  used  in  any  subsequent  commanads 
referencing  the  relation.  Failure  leads  to  a  zero  return  value,  the  actual  error  code  may  be  asked  for  by 
calling  dbplus_errno '). 


dbplus_prev  (php  4  >=  4.o.7rci) 


Get  previous  tuple  from  relation 


int  dbplus_prev  (resource  relation,  array  tuple) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


dbplus_currO  will  read  the  data  for  the  next  tuple  for  the  given  relation,  will  make  it  the  current  tuple 
and  will  pass  it  back  as  an  associative  array  in  t  upl  e. 

The  function  will  return  zero  (aka.  DBPLUS_ERR_NOERR)  on  success  or  a  db++  error  code  on  failure. 
See  dbplus_errcode ')  or  the  introduction  to  this  chapter  for  more  information  on  db++  error  codes. 

See  also  dbplus_first'),  dbplus_curr  ),  dbplus  next'),  and  dbpluslast 


dbplus_rchperm  (php  4  >=  4.o.7rci) 


Change  relation  permissions 


int  dbplus_rchperm  (resource  relation, 


int  mask,  string  user,  string  group ) 
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Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


dbplus_rchperm()  will  change  access  permissions  as  specified  by  mask,  user  and  group.  The  values 
for  these  are  operating  system  specific. 


dbplus_rcreate  (php  4  >=  4  o  7rci) 


resource  dbplus_rcreate  (string  name,  mixed  domlist 


boolean  overwrite ] ) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


dbplus_rcreate()  will  create  a  new  relation  named  name.  An  existing  relation  by  the  same  name  will 
only  be  overwritten  if  the  relation  is  currently  not  in  use  and  overwrite  is  set  to  TRUE. 

domlist  should  contain  the  domain  specification  for  the  new  relation  within  an  array  of  domain 
description  strings.  (  dbplus_rcreate()  will  also  accept  a  string  with  space  delimited  domain  description 
strings,  but  it  is  recommended  to  use  an  array).  A  domain  description  string  consists  of  a  domain  name 
unique  to  this  relation,  a  slash  and  a  type  specification  character.  See  the  db++  documentatiion, 
especially  the  dbcreate(l)  manpage,  for  a  description  of  available  type  specifiers  and  their  meanings. 


dbplus_rcrtexact  (php  4  >=  4.o.7rci) 


resource  dbplus_rcrtexact  (string  name,  resource  relation,  boolean  overwrite) 
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Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


dbplus_rcrtexact()  will  create  an  exact  but  empty  copy  of  the  given  relation  under  a  new  name.  An 
existing  relation  by  the  same  name  will  only  be  overwritten  if  overwrite  is  TRUE  and  no  other 
process  is  currently  using  the  relation. 


dbplus_rcrtlike  (php  4  >=  4.0.7rci) 


resource  dbplus_rcrtlike  (string  name,  resource  relation,  int  flag) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


dbplus_rcrtexact {)  will  create  an  empty  copy  of  the  given  relation  under  a  new  name,  but  with 
default  indices.  An  existing  relation  by  the  same  name  will  only  be  overwritten  if  overwrite  is  TRUE 
and  no  other  process  is  currently  using  the  relation. 


dbplus_resolve  <php  4  >=  4.o.7rci) 

Resolve  host  information  for  relation 


int  dbplus_resolve  (string  relation_name) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 
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dbplus_resolve()  will  try  to  resolve  the  given  relation_name  and  find  out  internal  server  id,  real 
hostname  and  the  database  path  on  this  host.  The  function  will  return  an  array  containing  these  values 
under  the  keys  ’sid’,  ’host’  and  ’host_path’  or  false  on  error. 

See  also  dbplus_tcl'). 


dbplus_rkeys  (php  4  >=  4 .0 .7rci) 


Specify  new  primary  key  for  a  relation 


resource  dbplus_rkeys  (resource  relation,  mixed  domlist) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


dbplus_rkeys()  will  replace  the  current  primary  key  for  relation  with  the  combination  of  domains 
specified  by  domlist. 

domlist  may  be  passed  as  a  single  domain  name  string  or  as  an  array  of  domain  names. 


dbplus_restorepos  (php  4  >=  4.o.7rcd 

??? 


int  dbplus_restorepos  (resource  relation,  array  tuple) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


Not  implemented  yet. 
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DB++ 


Open  relation  file  local 


resource  dbplus_ropen  (string  name ) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


dbplus_ropen()  will  open  the  relation  file  localy  for  quick  access  without  any  client/server  overhead. 
Access  is  read  only  and  only  dbplus_current()  and  dbplus_next ')  may  be  applied  to  the  returned 
relation. 


dbplus_rquery  (php  4  >=  4.o.7rcd 


Perform  local  (raw)  AQL  query 


int  dbplus_rquery  (string  query,  string  dbpath ) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


dbplus_rquery()  performs  a  local  (raw)  AQL  query  using  an  AQL  interpreter  embedded  into  the  db++ 
client  library.  dbplus_rquery()  is  faster  than  dbplus_aql ')  but  will  work  on  local  data  only. 


dbplus_rrename  (php  4  >=  4.o.7rci) 


Rename  a  relation 


int  dbplus_rrename  (resource  relation,  string  name) 
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Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


dbplus_rrename()  will  change  the  name  of  relation  to  name. 


dbplus_rsecindex  (php  4  >=  4.o.7rci) 


Create  a  new  secondary  index  for  a  relation 


resource  dbplus_rsecindex  (resource  relation,  mixed  domlist ,  int  type ) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


dbplus_rsecindex()  will  create  a  new  secondary  index  for  relation  with  consists  of  the  domains 
specified  by  domlist  and  is  of  type  type 

domlist  may  be  passed  as  a  single  domain  name  string  or  as  an  array  of  domain  names. 


dbplus_runlink(pHP4>=4  0  7Rci) 


Remove  relation  from  filesystem 


int  dbplus_runlink  (resource  relation) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


288 


DB++ 


dbplus_unlink()  will  close  and  remove  the  relation. 


dbplus_rzap  (php  4  >=  4.o.7rci) 


Remove  all  tuples  from  relation 


int  dbplus_rzap  (resource  relation) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


dbplus_rzap()  will  remove  all  tuples  from  relation. 


dbplus_savepos  <php  4  >=  4.o.7rcd 

??? 


int  dbplus_savepos  (resource  relation) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


Not  implemented  yet. 


dbplus_setindex  (php  4  >=  4.o.7rci) 

??? 


int  dbplus_setindex  (resource  relation, 


string  idx_name) 
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Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


Not  implemented  yet. 


dbplus_setindexbynumber  (php  4  >=  4.o.7rci) 

??? 


int  dbplus_setindexbynumber  (resource  relation,  int  idx_number) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


Not  implemented  yet. 


dbplUS_Sql  (PHP  4  >=  4.0.7RC1) 


Perform  SQL  query 


resource  dbplus_sql  (string  query, 


string  server, 


string  dbpath) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


Not  implemented  yet. 
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Execute  TCL  code  on  server  side 


int  dbplus_tcl  (int  sid,  string  script) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


A  db++  server  will  prepare  a  TCL  interpreter  for  each  client  connection.  This  interpreter  will  enable  the 
server  to  execute  TCL  code  provided  by  the  client  as  a  sort  of  stored  procedures  to  improve  the 
performance  of  database  operations  by  avoiding  client/server  data  transfers  and  context  switches. 

dbplus_tcl()  needs  to  pass  the  client  connection  id  the  TCL  script  code  should  be  executed  by. 
dbplus_resolveO  will  provide  this  connection  id.  The  function  will  return  whatever  the  TCL  code  returns 
or  a  TCL  error  message  if  the  TCL  code  fails. 

See  also  dbplus_resolveO- 


dbplus_tremove  (php  4  >=  4 .0 .7rci) 

Remove  tuple  and  return  new  current  tuple 

int  dbplus_tremove  (resource  relation,  array  tuple  [,  array  current]) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


dbplus_tremove()  removes  tuple  from  relation  if  it  perfectly  matches  a  tuple  within  the  relation. 
current,  if  given,  will  contain  the  data  of  the  new  current  tuple  after  calling  dbplus_tremove(). 
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??? 


int  dbplus_undo  (resource  relation) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


Not  implemented  yet. 


dbplus_undoprepare  (php  4  >=  4.o.7rcd 

??? 


int  dbplus_undoprepare  (resource  relation) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


Not  implemented  yet. 


dbplus_unlockrel  (php  4  >=  4 .0 .7Rci) 


Give  up  write  lock  on  relation 

int  dbplus_unlockrel  (resource  relation) 
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Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


dbpIus_unlockrel()  will  release  a  write  lock  previously  obtained  by  dbplus  lockrel '). 


dbplus_unselect  (php  4  >=  4 .0 .7rci) 


Remove  a  constraint  from  relation 


int  dbplus_unselect  (resource  relation) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


Calling  dbplus_unselect()  will  remove  a  constraint  previously  set  by  dhplus  tind  )  on  relation. 


dbplus_update  php 4 >=  4.o.7rcd 


Update  specified  tuple  in  relation 


int  dbplus_update  (resource  relation,  array  old,  array  new) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


dbplus_update()  replaces  the  tuple  given  by  old  with  the  data  from  new  if  and  only  if  old  completely 
matches  a  tuple  within  relation. 
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Request  exclusive  lock  on  relation 


int  dbplus_xlockrel  (resource  relation ) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


dbplus_xlockrel()  will  request  an  exclusive  lock  on  relation  preventing  even  read  access  from  other 
clients. 

See  also  dbplus_xunlockrek). 


dbplus_xunlockrel  <php  4  >=  4.o.7Rci) 


Free  exclusive  lock  on  relation 


int  dbplus_xunlockrel  (resource  relation) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


dbplus_xunlockrel()  will  release  an  exclusive  lock  on  relation  previously  obtained  by 
dbplus_xlocl<rcl '). 
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chdir  (PHP  3,  PHP  4  >=  4.0.0) 
cambia  de  directorio 

int  chdir  (string  directory) 


Cambia  el  directorio  PHP  actual  a  directory.  Devuelve  false  si  no  puede  cambiar  al  directorio, 
true  si  todo  va  bien. 


dir 


(PHP  3,  PHP  4  >=4.0.0) 


clase  directorio 


new  dir  (string  directory) 


Un  mecanismo  semi-orientado  a  objetos  para  leer  directorios.  El  parametro  directory  abre  el 
directorio.  Dos  propiedades  estan  disponibles  cuando  el  directorio  ha  sido  abierto.  La  propiedad  de 
manejo  puede  ser  usada  con  otras  funciones  de  directorios  tal  como  readdir'),  rewinddir  )  y  closedir')- 
La  propiedad  de  trayectoria  (path)  es  fijada  para  encaminar  el  directorio  que  ha  sido  abierto.  Tres 
metodos  estan  disponibles:  leer,  rebobinar  y  cerrar. 

Ejemplo  1.  dir()  Ejemplo 

$d  =  dir ( " / etc" ) ; 

echo  "Handle:  " . $d->handle . "<br>\n" ; 
echo  "Path:  " . $d->path . "<br>\n" ; 
while ( $entry=$d->read () )  { 

echo  $entry . " <br>\n" ; 

} 

$d->close ( ) ; 


closedir  (PHP  3,  PHP  4  >=4.0.0) 


cierra  el  manejador  de  directorios 


void  closedir  (int  dir_handle) 
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Cierra  la  secuencia  de  directorio  determinada  por  dir_handle.  La  secuencia  debe  de  haber  sido 
abierta  previamente  con  opendir'). 


opendir  (PHP  3,  PHP  4  >=  4.0.0) 

abre  el  manejador  de  directorios 

int  opendir  (string  path) 


Devuelve  un  manejador  de  directorio  para  ser  usado  con  las  llamadas  closedir'),  readdir')  y  rewinddir). 


readd  ir  (PHP  3,  PHP  4  >=  4.0.0) 

lee  las  entradas  del  manejador  de  directorios 

string  readdir  (int  dir_handle) 


Devuelve  el  nombre  del  siguiente  fichero  en  el  directorio.  Los  nombres  de  ficheros  no  son  devueltos  en 
ningun  orden  especial . 

Ejemplo  1.  Listar  todos  los  ficheros  en  un  directorio 


<?php 

$handle=opendir ( '  . '  )  ; 

echo  "Directory  handle:  $handle\n"; 

echo  "Files :\n"; 

while  ($file  =  readdir ($handle) )  { 

echo  "$file\n"; 

} 

closedir ( $ handle ) ; 

?> 


Tener  en  cuenta  que  readdir))  devolvera  tambien  .  y  ..  Si  no  quereis  estas  entradas  podeis  borrarlas: 

Ejemplo  2.  Listar  todos  los  ficheros  en  un  directorio  excepto  .  y  .. 


<?php 

$handle=opendir ( '  . '  )  ; 
while  ($file  =  readdir ($handle) )  { 

if  ($file  ! =  &&  $f ile  !=  { 
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echo  "$file\n"; 

} 

} 

closedir ($handle) ; 

?> 


rewinddir  (php  3,  php  4  >=  4.0.0) 

rebobinar  el  manejador  de  directorios 

void  rewinddir  (int  dir_handle) 


Inizializa  la  secuencia  de  directorio  determinada  por  dir_handle  al  principio  del  directorio. 
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Aviso 

This  module  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  these 
functions,  these  function  names,  in  concreto  ANYTHING  documented  here  can 
change  in  a  future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this 
module  at  your  own  risk. 


Estas  funciones  son  disponibles  solamente  si  PHP  fue  configurado  con  — with-dom=  [dir]  ,  usando  al 
libreria  de  XML  de  GNOME.  Usted  va  a  necesitar  como  mi'nimo  libxml-2.0.0  (la  version  beta  no 
trabajara).  Estas  functiones  fueron  anadidas  en  PHP4. 

Este  module  define  las  siguientes  constantes: 


Tabla  1.  Constantes  de  XML 


Constante 

Valor 

Description 

XML ELEMENT NODE 

1 

XML ATTRIBUTE NODE 

2 

XML TEXT N  ODE 

3 

XML_CDATA_SECTION_NODE 

4 

XML ENTITY REF NODE 

5 

XML ENTITY NODE 

6 

XML PI NODE 

7 

XML COMMENT NODE 

8 

XML DOCUMENT NODE 

9 

XML_DOCUMENT_TYPE_NOD 

ED 

XML_DOCUMENT_FRAG_NOE 

H 

XML NOTATION NODE 

12 

XML GLOBAL NAMESPACE 

1 

XML_LOCAL_NAMESPACE 

2 

Este  modulo  define  un  numero  de  clases.  Las  funciones  de  DOM  XML  devuelven  un  arbol  conteniendo 
la  structure  del  documento  XML,  en  el  cual  cada  nodo  es  un  objecto  perteneciente  a  una  de  estas  clases. 
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xmldoc  (PHP  4  >=  4.0.0) 

Crea  un  objecto  DOM  representando  un  documento  XML 

object  xmldoc  (string  str) 


Esta  funcion  analiza  el  documento  XML  contenido  en  el  texto  str  y  devuelve  un  objecto  de  clase 
"Documento  Dom",  que  tiene  las  propiedades  "doc"  (resource),  "version"  (string)  y  "typo"  (long). 


xmldocfile(PHP4>=4oo) 

Creat  un  objecto  DOM  a  partir  de  un  archivo  XML 

object  xmldocfile  (string  filename) 


Esta  funcion  analiza  el  documento  XML  contenido  en  el  archivo  referido  en  filename  y  devuelve  un 
objecto  de  clase  "Documento  Dom",  que  tiene  las  propiedades  "doc"  (resource),  "version"  (string)  y 
"typo"  (long). 


xmltree  (php4>=  4  0  0) 

Crea  un  arbol  de  objectos  PHP  a  partir  del  un  document  XML 

object  xmltree  (string  str) 


Esta  funcion  analiza  el  documento  XML  contenido  en  el  texto  str  y  devuelve  in  arbol  de  objectos  PHP 
representando  el  documento  analizado. 
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XXIII.  Error  Handling  and  Logging  Functions 

These  are  functions  dealing  with  error  handling  and  logging.  They  allow  you  to  define  your  own  error 
handling  rules,  as  well  as  modify  the  way  the  errors  can  be  logged.  This  allows  you  to  change  and 
enhance  error  reporting  to  suit  your  needs. 

With  the  logging  functions,  you  can  send  messages  directly  to  other  machines,  to  an  email  (or  email  to 
pager  gateway!),  to  system  logs,  etc.,  so  you  can  selectively  log  and  monitor  the  most  important  parts  of 
your  applications  and  websites. 

The  error  reporting  functions  allow  you  to  customize  what  level  and  kind  of  error  feedback  is  given, 
ranging  from  simple  notices  to  customized  functions  returned  during  errors. 
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errorjog  (PHP  3,  PHP  4  >=  4.0.0) 


envfa  un  mensaje  de  error  a  algun  lugar 


int  error_log  (string  message,  int  message_type  [,  string  destination  [, 
string  ext ra_headers]  ]  ) 


Envfa  un  mensaje  de  error  al  log  de  errores  del  servidor  web,  a  un  puerto  TCP  o  a  un  fichero.  El  primer 
parametro,  message  (mensaje),  es  el  mensaje  de  error  que  debe  ser  registrado.  El  segundo  parametro, 
message_type  (tipo  de  mensaje)  indica  el  lugar  al  que  debe  dirigirse: 


Tabla  1.  error_log()  tipos  de  log 


0 

message  es  enviado  al  registro  de  sistema  de  PHP, 
utilizando  el  mecanismo  de  registro  de  sistema  del 
Sistema  Operativo,  o  a  un  fichero,  dependiendo  del 
valor  de  la  directiva  de  configuration  errorjog 

1 

message  es  enviado  por  correo  electronico  a  la 
direccion  del  parametro  destination  (destino). 
Este  es  el  unico  tipo  de  mensaje  donde  se  utiliza  el 
cuarto  parametro,  extra_headers.  Este  tipo  de 
mensaje  utiliza  la  misma  funcionalidad  interna  que 
mail')  realiza. 

2 

message  es  enviado  a  traves  de  la  conexion  de 
depuracion  de  PHP.  Esta  opcion  esta  disponible  solo 
si  la  depuracion  remota  ha  sido  activada  En  este 
caso  el  parametro  destination  especifica  el 
nombre  de  host  o  direccion  IP  y,  opcionalmente,  el 
numero  de  puerto  del  socket  que  recibe  la 
information  de  depuracion. 

3 

message  es  anadido  al  fichero  destination. 

Ejemplo  1.  error_log()  ejemplos 

//  Send  notification  through  the  server  log  if  we  can  not 

//  connect  to  the  database. 

if  ( ! Ora_Logon ($username,  $password) )  { 

errorjog  ( "Oracle  database  not  available!",  0); 

} 

//  Notify  administrator  by  email  if  we  run  out  of  FOO 
if  (! ($foo  =  allocate_new_foo ( ) )  { 

errorjog  (  "Big  trouble,  we're  all  out  of  FOOs  !  "  ,  1, 
"operator@mydomain . com" ) ; 
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} 

//  other  ways  of  calling  error_log() : 

error_log ("You  messed  up!",  2,  "127.0.0.1:7000"); 

error_log ( " You  messed  up!",  2,  "loghost"); 

error_log ( " You  messed  up!",  3,  " /var/tmp/my-errors . log" ) ; 


error_reporting  (PHP  3,  PHP  4  >=  4.0.0) 

establece  que  errores  PHP  son  registrados 

int  error_reporting  ([int  level]) 


Establece  el  nivel  de  registro  de  los  errores  PHP  y  devuelve  el  nivel  anterior.  El  nivel  de  registro  es  una 
mascara  de  bits  de  los  valores  siguientes  (siga  los  enlaces  a  los  valores  internos  para  obtener  sus 
significados): 


Tabla  1.  error_reporting()  valores  de  bit 


valor 

nombre  interno 

1 

E ERROR 

2 

E WARNING 

4 

E PARSE 

8 

E NOTICE 

16 

E CORE ERROR 

32 

E_CORE_WARNING 

restore_error_handler  (php  4 ) 


Restores  the  previous  error  handler  function 


void  restore_error_handler  (void) 


Used  after  changing  the  error  handler  function  using  set_error_handlerO,  to  revert  to  the  previous  error 
handler  (which  could  be  the  built-in  or  a  user  defined  function) 

See  also  error_reporting '),  set_error_handlerO,  trigger_error  ),  user  error'j 
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set_error  handler (php4) 


Sets  a  user-defined  error  handler  function. 


string  set_error_handler  (string  error_handler) 


Sets  a  user  function  ( error_handler )  to  handle  errors  in  a  script.  Returns  the  previously  defined 
error  handler  (if  any),  or  false  on  error.  This  function  can  be  used  for  defining  your  own  way  of 
handling  errors  during  runtime,  for  example  in  applications  in  which  you  need  to  do  cleanup  of  data/files 
when  a  critical  error  happens,  or  when  you  need  to  trigger  an  error  under  certain  conditions  (using 
trigger_errot )) 

The  user  function  needs  to  accept  2  parameters:  the  error  code,  and  a  string  describing  the  error.  The 
example  below  shows  the  handling  of  internal  exceptions  by  triggering  errors  and  handling  them  with  a 
user  defined  function: 

Ejemplo  1.  Error  handling  with  set_error_handler()  and  triggererror) 


<?php 

//  redefine  the  user  error  constants  -  PHP4  only 
define  (FATAL, E_USER_ERROR) ; 
define  (ERROR, E_USER_WARNING) ; 
define  (WARNING, E_USER_NOTICE) ; 

/ /  set  the  error  reporting  level  for  this  script 
error_reporting  (FATAL  +  ERROR  +  WARNING) ; 

/ /  error  handler  function 

function  myErrorHandler  ($errno,  $errstr)  { 
switch  ($errno)  { 
case  FATAL: 

echo  "<b>FATAL</b>  [$errno]  $errstr<br>\n" ; 

echo  "  Fatal  error  in  line  " . _ LINE _ . "  of  file  " . _ FILE. 

echo  ",  PHP  " ,PHP_VERSION. "  ( " . PHP_OS . " ) <br>\n " ; 

echo  "Aborting  ... <br>\n" ; 

exit  -1; 

break; 

case  ERROR: 

echo  "<b>ERROR</b>  [$errno]  $errstr<br>\n" ; 
break; 

case  WARNING: 

echo  "<b>WARNING</b>  [$errno]  $errstr<br>\n" ; 

break; 

default : 

echo  "Unkown  error  type:  [$errno]  $errstr<br>\n" ; 
break; 

} 

} 
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/ /  function  to  test  the  error  handling 
function  scale_by_log  ($vect,  $scale)  { 

if  (  ! is_numeric ($scale)  I |  $scale  <=  0  ) 

trigger_error ( " log (x)  for  x  <=  0  is  undefined,  you  used:  scale  =  $scale", 
FATAL) ; 

if  ( ! is_array ( $vect ) )  { 

trigger_error (" Incorrect  input  vector,  array  of  values  expected",  ERROR); 
return  null; 

} 

for  ($i=0;  $i<count ( $vect ) ;  $i++)  { 

if  ( ! is_numeric ($vect [ $ i ] ) ) 

trigger_error ( "Value  at  position  $i  is  not  a  number,  using  0  (zero)", 
WARNING) ; 

$temp[$i]  =  log($scale)  *  $vect[$i]; 

} 

return  $temp; 

} 

//  set  to  the  user  defined  error  handler 

$old_error_handler  =  set_error_handler ( "myErrorHandler " ) ; 

//  trigger  some  errors,  first  define  a  mixed  array  with  a  non-numeric  item 
echo  "vector  a\n"; 

$a  =  array (2, 3, "foo", 5 . 5, 43 . 3, 21 . 11)  ; 
print_r ( $a) ; 

//  now  generate  second  array,  generating  a  warning 

echo  " - \nvector  b  -  a  warning  (b  =  log  (PI)  *  a)\n"; 

$b  =  scale_by_log ( $a,  M_PI) ; 
print_r ( $b) ; 

//  this  is  trouble,  we  pass  a  string  instead  of  an  array 

echo  " - \nvector  c  -  an  error\n"; 

$c  =  scale_by_log ( "not  array", 2. 3); 
var_dump ( $  c ) ; 

//  this  is  a  critical  error,  log  of  zero  or  negative  number  is  undefined 

echo  " - \nvector  d  -  fatal  error\n"; 

$d  =  scale_by_log ( $a,  -2.5); 

?> 


And  when  you  run  this  sample  script,  the  output  will  be 


vector  a 
Array 
( 

[0]  =>  2 

[1]  =>  3 

[2]  =>  foo 
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[3]  =>  5.5 

[4]  =>  43.3 

[5]  =>  21.11 


vector  b  -  a  warning  (b  =  log (PI)  *  a) 

<b>WARNING</b>  [1024]  Value  at  position  2  is  not  a  number,  using  0  (zero) <br> 
Array 
( 


0] 

=  > 

2.2894597716988 

1] 

=  > 

3 .4341896575482 

2] 

=  > 

0 

3] 

=  > 

6.2960143721717 

4] 

=  > 

49.566804057279 

5] 

=  > 

24 .165247890281 

vector  c  -  an  error 

<b>ERROR</b>  [512]  Incorrect  input  vector,  array  of  values  expected<br> 

NULL 

vector  d  -  fatal  error 

<b>FATAL</b>  [256]  log  (x)  for  x  <=  0  is  undefined,  you  used:  scale  =  -2.5<br> 
Fatal  error  in  line  16  of  file  trigger_error . php,  PHP  4 . 0 . Ipl2  (Linux) <br> 
Aborting. . . <br> 


See  also  error_reporting '),  restore_error_handler),  trigger_error'),  user  error  ) 


trigger_error  (PHP  4) 


Generates  a  user-level  error/waming/notice  message 


void  trigger_error  (string  error_msg  [,  int  error_type] ) 


Used  to  trigger  a  user  error  condition,  it  can  be  used  by  in  conjunction  with  the  built-in  error  handler,  or 
with  a  user  defined  function  that  has  been  set  as  the  new  error  handler  (set_error_handler()).  This 
function  is  useful  when  you  need  to  generate  a  particular  response  to  an  exception  at  runtime.  For 
example: 

if  (assert  ($divisor  ==  0)) 

trigger_error  ("Cannot  divide  by  zero",  E_USER_ERROR) ; 


Nota:  See  set_error_handler;)  for  a  more  extensive  example. 
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See  also  error_reporting  [),  set_error_handlerO,  restore_error_handler'),  user_error  ') 

user_error(pHP4>=4oo) 

Generates  a  user-level  error/waming/notice  message 

void  user_error  (string  error_msg  [,  int  error_type ]) 

This  is  an  alias  for  the  function  trigger_crror'j. 

See  also  error  reporting set_error_handler\),  restore_error_handler(),  and  trigger_error ') 
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These  functions  allow  you  to  access  FrontBase  database  servers.  In  order  to  have  these  functions 
available,  you  must  compile  php  with  fbsql  support  by  using  the  — with-fbsql  option.  If  you  use  this 
option  without  specifying  the  path  to  fbsql,  php  will  search  for  the  fbsql  client  libraries  in  the  default 
installation  location  for  the  platform.  Users  who  installed  FrontBase  in  a  non  standard  directory  should 
always  specify  the  path  to  fbsql:  — with-fbsql=/path/to/fbsql.  This  will  force  php  to  use  the 
client  libraries  installed  by  FrontBase,  avoiding  any  conflicts. 

More  information  about  FrontBase  can  be  found  at  http://www.frontbase.com/. 

Documentation  for  FrontBase  can  be  found  at  http://www.frontbase.com/cgi- 
bin/WebObjects/FrontBase.woa/wa/productsPage?currentPage=Documentation. 

Frontbase  support  has  been  added  to  PHP  4.0.6. 
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f  bsql_affected_rows  (php  4  >=  4.0.6) 

Get  number  of  affected  rows  in  previous  FrontBase  operation 

int  fbsql_af fected_rows  (int  [ link_identifier ]) 


fbsql_affected_rows()  returns  the  number  of  rows  affected  by  the  last  INSERT,  UPDATE  or  DELETE 
query  associated  with  link_identifier.  If  the  link  identifier  isn’t  specified,  the  last  link  opened  by 
fbsql_connectO  is  assumed. 

Nota:  If  you  are  using  transactions,  you  need  to  call  fbsql_affected_rows()  after  your  INSERT, 
UPDATE,  or  DELETE  query,  not  after  the  commit. 


If  the  last  query  was  a  DELETE  query  with  no  WHERE  clause,  all  of  the  records  will  have  been  deleted 
from  the  table  but  this  function  will  return  zero. 

Nota:  When  using  UPDATE,  FrontBase  will  not  update  columns  where  the  new  value  is  the  same  as 
the  old  value.  This  creates  the  possiblity  that  fbsql_affected_rows()  may  not  actually  equal  the 
number  of  rows  matched,  only  the  number  of  rows  that  were  literally  affected  by  the  query. 


If  the  last  query  failed,  this  function  will  return  -1. 
See  also:  fbsql_num_rows  [). 


f  bsql_autocommit  (php  4  >=  4.o.6) 


Enable  or  disable  autocommit. 


bool  fbsql_autocommit  (resource  link_identifier,  bool  [OnOff]) 


fbsql_autocommit()  returns  the  current  autocommit  status,  if  the  optional  OnOff  parameter  is  given  the 
auto  commit  status  will  be  changed.  With  OnOff  set  to  true  each  statement  will  be  commited 
automatically,  if  no  errors  was  found.  With  OnOff  set  to  false  the  user  must  commit  or  rollback  the 
transaction  using  either  fbsql_commitO  or  fbsql_rollback'). 

See  also:  fbsql_commit()  and  tbsql  rollhack  ) 
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Change  logged  in  user  of  the  active  connection 


resource  fbsql_change_user  (string  user,  string  password,  string  [database] , 
int  [link_identifier]) 


fbsql_change_user()  changes  the  logged  in  user  of  the  current  active  connection,  or  the  connection 
given  by  the  optional  parameter  link_identifier.  If  a  database  is  specified,  this  will  default  or  current 
database  after  the  user  has  been  changed.  If  the  new  user  and  password  authorization  fails,  the  current 
connected  user  stays  active. 


fbsql_close  (PHP  4  >=  4.0.6) 


Close  FrontBase  connection 


boolean  fbsql_close  (resource  [link_identifier] ) 


Returns:  true  on  success,  false  on  error. 

fbsql_close()  closes  the  connection  to  the  FrontBase  server  that’s  associated  with  the  specified  link 
identifier.  If  link_identifier  isn’t  specified,  the  last  opened  link  is  used. 

Using  fbsql_close()  isn’t  usually  necessary,  as  non-persistent  open  links  are  automatically  closed  at  the 
end  of  the  script’s  execution. 

Ejemplo  1.  fbsql_close()  example 


<?php 

$link  =  fbsql_connect  ( " localhost " ,  "_SYSTEM",  "secret") 
or  die  ("Could  not  connect"); 
print  ("Connected  successfully"); 
fbsql_close  ($link) ; 

?> 


See  also:  fbsql_connect ))  and  fbsqLpconnccC). 


f  bsq  l_com  m  it  <php  4  >=  4.0.6) 


Commits  a  transaction  to  the  database 
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bool  fbsql_commit  (resource  [link_identifier ]) 

Returns:  true  on  success,  false  on  failure. 

fbsql_commit()  ends  the  current  transaction  by  writing  all  insertsm  updates  and  deletes  to  the  disk  and 
unlucking  all  row  and  table  locks  held  by  the  transaction.  This  command  is  only  needed  if  autocommit  is 
set  to  false. 

See  also:  fbsql_autocommit ')  and  thsql  rollback  ') 


f  bsq  l_con  nect  <php  4  >=  4.0.6) 


Open  a  connection  to  a  FrontBase  Server 


resource  fbsql_connect  (string  [hostname] ,  string  [username] ,  string 
[password ] ) 


Returns  a  positive  FrontBase  link  identifier  on  success,  or  an  error  message  on  failure. 

fbsql_connect()  establishes  a  connection  to  a  FrontBase  server.  The  following  defaults  are  assumed  for 
missing  optional  parameters:  hostname  =  ’null’,  username  =  ’_SYSTEM’  and  password  = 
empty  password. 

If  a  second  call  is  made  to  fbsql_connect()  with  the  same  arguments,  no  new  link  will  be  established,  but 
instead,  the  link  identifier  of  the  already  opened  link  will  be  returned. 

The  link  to  the  server  will  be  closed  as  soon  as  the  execution  of  the  script  ends,  unless  it’s  closed  earlier 
by  explicitly  calling  fbsq[_close'). 

Ejemplo  1.  fbsql_connect()  example 


<?php 

$link  =  fbsql_connect  ( " localhost " ,  "_SYSTEM",  "secret") 
or  die  ("Could  not  connect") ; 
print  ("Connected  successfully"); 
fbsql_close  ($link) ; 


?> 


See  also  fbsql_pconnect ')  and  fbsql_close(). 
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f  bsq  l_create_db  (php  4  >=  4.0.6) 


Create  a  FrontBase  database 


bool  fbsql_create_db  (string  database  name,  resource  [ link_identifier ]) 


fbsql_create_db()  attempts  to  create  a  new  database  on  the  server  associated  with  the  specified  link 
identifier. 

Ejemplo  1.  fbsql_create_db()  example 

<?php 

$link  =  fbsql_pconnect  (  " localhost " ,  "_SYSTEM",  "secret") 
or  die  ("Could  not  connect"); 
if  ( fbsql_create_db  ("my_db"))  { 

print ( "Database  created  successfully\n" ) ; 

}  else  { 

printf ( "Error  creating  database:  %s\n",  fbsql_error  ()); 

} 

?> 


See  also:  thsql  drop  dh '). 


f bsql_create_blob  php  4  cvs  oniy) 


Create  a  BLOB 


string  fbsql_create_blob  (string  blob_data,  resource  [ link_identifier ]) 


Returns:  A  resource  handle  to  the  newly  created  blob. 

fbsql_create_blob()  creates  a  blob  from  blob_data.  The  returned  resource  handle  can  be  used  with  insert 
and  update  commands  to  store  the  blob  in  the  database. 

Ejemplo  1.  fbsql_create_blob()  example 


<?php 

$link  =  fbsql_pconnect  ("localhost",  "_SYSTEM",  "secret") 
or  die  ("Could  not  connect"); 

$filename  =  "blobfile.bin"; 

$fp  =  fopen ($filename,  "rb"); 

$blobdata  =  fread($fp,  f ilesize ( $f ilename) ) ; 
fclose ( $  f p ) ; 
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$blobHandle  =  fbsql_create_blob ( $blobdata,  $link) ; 

$ sql  =  "INSERT  INTO  BLOB_TABLE  (BLOB_COLUMN)  VALUES  ( $blobHandle )  ; " ; 
$rs  =  fbsql_query ($sql,  $link) ; 


See  also:  fbsql_create_clob  3,  fbsql_read_blobO,  tbsql  read  clob '),  and  tbsql_set_lob_mode  ). 


f  bsql_create_clob  <php  4  cvs  0my) 


Create  a  CLOB 


string  fbsql_create_clob  (string  clob_data,  resource  [ link_identifier ]) 


Returns:  A  resource  handle  to  the  newly  created  CLOB. 

fbsql_create_clob()  creates  a  clob  from  clob_data.  The  returned  resource  handle  can  be  used  with  insert 
and  update  commands  to  store  the  clob  in  the  database. 

Ejemplo  1.  fbsql_create_clob()  example 


<?php 

$link  =  fbsql_pconnect  ( " localhost " ,  "_SYSTEM",  "secret") 
or  die  ("Could  not  connect") ; 

$filename  =  "clob_file.txt"; 

$fp  =  fopen  ($filename,  "rb"); 

Sclobdata  =  fread($fp,  f ilesize ( $f ilename) ) ; 
fclose ( $  f p ) ; 

SclobHandle  =  fbsql_create_clob ( Sclobdata,  $link) ; 

$  sql  =  "INSERT  INTO  CLOB_TABLE  (CLOB_COLUMN)  VALUES  ( $clobHandle )  ; " ; 
$rs  =  fbsql_query ($sql,  $link) ; 


See  also:  fbsql_create_blob'),  fbsql_read_blob(),  fbsql_read_clob'),  and  fbsql_set_lob_mode3. 


f  bsql_database_password  (php  4  >=  4  o  6) 


Sets  or  retreives  the  password  for  a  FrontBase  database 
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string  fbsql_database_password  (resource  link_identifier,  string 
[database_password ] ) 


Returns:  The  database  password  for  the  database  represented  by  the  link  identifier. 

fbsql_database_password()  sets  and  retreives  the  database  password  for  the  current  database,  if  the 
second  optional  parameter  is  given  the  function  sets  the  database  password  for  the  database  on  the  server 
that’s  associated  with  the  specified  link  identifier.  If  no  link  identifier  is  specified,  the  last  opened  link  is 
assumed.  If  no  link  is  open,  the  function  will  try  to  establish  a  link  as  if  fbsql_connect  ')  was  called,  and 
use  it. 

See  also:  fbsql_connect ')  and  fbsql_pconnect'). 


f  bsq  l_data_seek  {php  4  >=  4.0.6) 


Move  internal  result  pointer 


bool  fbsql_data_seek  (resource  result_identifier,  int  row_number) 


Returns:  true  on  success,  false  on  failure. 

fbsql_data_seek()  moves  the  internal  row  pointer  of  the  FrontBase  result  associated  with  the  specified 
result  identifier  to  point  to  the  specified  row  number.  The  next  call  to  fbsql_fetch_row\)  would  return  that 
row. 

Row_number  starts  at  0. 

Ejemplo  1.  fbsql_data_seek()  example 

<?php 

$link  =  fbsql_pconnect  ( "localhost " ,  "_SYSTEM",  "secret") 
or  die  ("Could  not  connect"); 

fbsql_select_db  ("samp_db") 

or  die  ("Could  not  select  database"); 

$query  =  "SELECT  last_name,  first_name  FROM  friends;"; 

$result  =  fbsql_query  ($query) 
or  die  ("Query  failed"); 

#  fetch  rows  in  reverse  order 

for  ($i  =  fbsql_num_rows  ($result)  -  1;  $i  >=0;  $i — )  { 

if  ( ! fbsql_data_seek  ($result,  $i) )  { 

printf  ("Cannot  seek  to  row  %d\n",  $i); 
continue ; 

} 
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if ( ! ($row  =  fbsql_f etch_ob ject  ($result))) 
continue ; 

printf("%s  %s<BR>\n",  $row->last_name,  $row->f irst_name) ; 

} 

fbsql_f ree_result  ($result); 


f  bsql_db_query  (php  4  >=  4.0.6) 


Send  a  FrontBase  query 


resource  fbsql_db_query  (string  database,  string  query,  resource 
[ link_identifier ] ) 


Returns:  A  positive  FrontBase  result  identifier  to  the  query  result,  or  false  on  error. 

fbsql_db_query()  selects  a  database  and  executes  a  query  on  it.  If  the  optional  link  identifier  isn’t 
specified,  the  function  will  try  to  find  an  open  link  to  the  FrontBase  server  and  if  no  such  link  is  found 
it’ll  try  to  create  one  as  if  fbsql_connect')  was  called  with  no  arguments 

See  also  fbsql_connectO- 


f  bsql_db_status  (php  4  >=  4.o.7rcd 


Get  the  status  for  a  given  database 


int  fbsql_db__status  (string  database_name ,  resource  [link_identifier] ) 


Returns:  An  integer  value  with  the  current  status. 

fbsql_db_status()  requests  the  current  status  of  the  database  specified  by  database_name.  If  the 
link_identifier  is  omitted  the  default  link_identifier  will  be  used. 

The  return  value  can  be  one  of  the  following  constants: 

•  false  -  The  exec  handler  for  the  host  was  invalid.  This  error  will  ocour  when  the  link_identifier 
connects  directly  to  a  database  by  using  a  port  number.  FBExec  can  be  available  on  the  server  but  no 
connection  has  been  made  for  it. 
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•  FBSQL_UNKNOWN  -  The  Status  is  unknown. 

•  FBSQL_STOPPED  -  The  database  is  not  running.  Use  fbsql_start_db ')  to  start  the  database. 

•  FBSQL_STARTING  -  The  database  is  starting. 

•  FBSQL_RUNNING  -  The  database  is  running  and  can  be  used  to  perform  SQL  operations. 

•  FBSQL_S TOPPING  -  The  database  is  stopping. 

•  FBSQL_NOEXEC  -  FBExec  is  not  running  on  the  server  and  it  is  not  possible  to  get  the  status  of  the 
database. 

See  also:  fbsql_start_dbQ  and  fbsql_stop_db '). 


f  bsql_drop_db  (php  4  >=  4.0.6) 

Drop  (delete)  a  FrontBase  database 

bool  fbsql_drop_db  (string  database_name,  resource  [link_identifier] ) 


Returns:  true  on  success,  false  on  failure. 

fbsql_drop_db()  attempts  to  drop  (remove)  an  entire  database  from  the  server  associated  with  the 
specified  link  identifier. 


f  bsql_errno  (php  4  >=  4 .0 .6> 

Returns  the  numerical  value  of  the  error  message  from  previous  FrontBase  operation 

int  fbsql_errno  (resource  [link_identifier]) 


Returns  the  error  number  from  the  last  fbsql  function,  or  0  (zero)  if  no  error  occurred. 

Errors  coming  back  from  the  fbsql  database  backend  dont  issue  warnings.  Instead,  use  fbsql_errno()  to 
retrieve  the  error  code.  Note  that  this  function  only  returns  the  error  code  from  the  most  recently 
executed  fbsql  function  (not  including  fbsql_erroi\)  and  fbsql_errno()),  so  if  you  want  to  use  it,  make 
sure  you  check  the  value  before  calling  another  fbsql  function. 

<?php 

fbsql_connect ( "marliesle" ) ; 

echo  fbsql_errno ( ) " . fbsql_error ( ) . "<BR>"; 

fbsql_select_db ( "nonexistentdb" )  ; 

echo  fbsql_errno ( ) " . fbsql_error ( ) . "<BR>"; 
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$conn  =  fbsql_query (" SELECT  *  FROM  nonexistenttable; " ) ; 
echo  fbsql_errno ( ) . fbsql_error ( ) . "<BR>"; 

?> 


See  also:  fbsql_error ')  and  fbsql_warnings'). 


fbsql_error(PHP4>=4  0  6) 

Returns  the  text  of  the  error  message  from  previous  FrontBase  operation 

string  fbsql_error  (resource  [link_identifier ]) 


Returns  the  error  text  from  the  last  fbsql  function,  or  "  (the  empty  string)  if  no  error  occurred. 

Errors  coming  back  from  the  fbsql  database  backend  dont  issue  warnings.  Instead,  use  fbsql_error()  to 
retrieve  the  error  text.  Note  that  this  function  only  returns  the  error  text  from  the  most  recently  executed 
fbsql  function  (not  including  fbsql_error()  and  fbsql_errno')),  so  if  you  want  to  use  it,  make  sure  you 
check  the  value  before  calling  another  fbsql  function. 

<?php 

fbsql_connect ( "marliesle" ) ; 

echo  fbsql_errno ( ) " . fbsql_error ( ) . "<BR>"; 

fbsql_select_db ( "nonexistentdb" ) ; 

echo  fbsql_errno ( ) " . fbsql_error ( ) . "<BR>"; 

$conn  =  fbsql_query (" SELECT  *  FROM  nonexistenttable;"); 
echo  fbsql_errno ( ) " . fbsql_error ( ) . "<BR>"; 

?> 


See  also:  fbsql_errnoO  and  fbsql_warningsO. 


f  bsq  l_fetch_array  <php  4  >=  4.0.6) 

Fetch  a  result  row  as  an  associative  array,  a  numeric  array,  or  both 

array  fbsql_fetch_array  (resource  result,  int  [result_type ]) 


Returns  an  array  that  corresponds  to  the  fetched  row,  or  false  if  there  are  no  more  rows. 
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fbsql_fetch_array()  is  an  extended  version  of  fbsql_fetch_row ').  In  addition  to  storing  the  data  in  the 
numeric  indices  of  the  result  array,  it  also  stores  the  data  in  associative  indices,  using  the  field  names  as 
keys. 

If  two  or  more  columns  of  the  result  have  the  same  field  names,  the  last  column  will  take  precedence.  To 
access  the  other  column(s)  of  the  same  name,  you  must  the  numeric  index  of  the  column  or  make  an  alias 
for  the  column. 

select  tl.fl  as  foo  t2 . f 1  as  bar  from  tl,  t2 


An  important  thing  to  note  is  that  using  fbsql_fetch_array()  is  NOT  significantly  slower  than  using 
tbsql_fetch_row'),  while  it  provides  a  significant  added  value. 

The  optional  second  argument  result_type  in  fbsql_fetch_array()  is  a  constant  and  can  take  the 
following  values:  FBSQL_ASSOC,  FBSQL_NUM,  and  FBSQL_BOTH. 

For  further  details,  see  also  fbsq[_fetch_row ')  and  fbsql_fetch_assoc '). 

Ejemplo  1.  fbsql_fetch_array()  example 


<?php 

fbsql_connect  ($host,  $user,  $password) ; 

$result  =  fbsql_db_query  ( "database" , "select  user_id,  fullname  from  table"); 
while  ($row  =  fbsql_f etch_array  ($result))  { 

echo  "user_id:  " . $row [ "user_id" ] . "<br>\n" ; 
echo  "user_id:  " . $row [ 0 ] . "<br>\n" ; 
echo  "fullname:  ". $row [" fullname" ]. "<br>\n" ; 
echo  "fullname:  " . $row [ 1 ] . "<br>\n" ; 

} 

fbsql_f ree_result  ($result); 

?> 


f  bsql_fetch_assoc  (php  4  >=  4.0.6) 


Fetch  a  result  row  as  an  associative  array 


array  fbsql_fetch_assoc  (resource  result ) 


Returns  an  associative  array  that  corresponds  to  the  fetched  row,  or  false  if  there  are  no  more  rows. 

fbsql_fetch_assoc()  is  equivalent  to  calling  fbsql_fetch_array ')  with  FBSQL_ASSOC  for  the  optional 
second  parameter.  It  only  returns  an  associative  array.  This  is  the  way  fbsql_fetch_arrayO  originally 
worked.  If  you  need  the  numeric  indices  as  well  as  the  associative,  use  fbsq  l_tetc  h_array '). 
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If  two  or  more  columns  of  the  result  have  the  same  field  names,  the  last  column  will  take  precedence.  To 
access  the  other  column(s)  of  the  same  name,  you  must  use  fbsql_fetch_arrayO  and  have  it  return  the 
numeric  indices  as  well. 

An  important  thing  to  note  is  that  using  fbsql_fetch_assoc()  is  NOT  significantly  slower  than  using 
tbsql  t'etch  row'),  while  it  provides  a  significant  added  value. 

For  further  details,  see  also  fbsq[_fetch_row  ')  and  fbsql_fetch_arrayO- 

Ejemplo  1.  fbsql_fetch_assoc()  example 


<?php 

fbsql_connect  ($host,  $user,  $password) ; 

$result  =  fbsql_db_query  ( "database" , "select  *  from  table"); 
while  ($row  =  fbsql_f etch_assoc  ($result))  { 
echo  $row [ "user_id" ] ; 
echo  $row [ " fullname " ] ; 

} 

fbsql_f ree_result  ($result); 

?> 


fbsql_fetch_field  (php4>=4.o.6) 

Get  column  information  from  a  result  and  return  as  an  object 

object  fbsql_fetch_field  (resource  result,  int  [ field_offset] ) 


Returns  an  object  containing  field  information. 

fbsql_fetch_field()  can  be  used  in  order  to  obtain  information  about  fields  in  a  certain  query  result.  If  the 
field  offset  isn’t  specified,  the  next  field  that  wasn’t  yet  retrieved  by  fbsql_fetch_field()  is  retrieved. 

The  properties  of  the  object  are: 

•  name  -  column  name 

•  table  -  name  of  the  table  the  column  belongs  to 

•  max_length  -  maximum  length  of  the  column 

•  not_null  -  1  if  the  column  cannot  be  null 

•  type  -  the  type  of  the  column 
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Ejemplo  1.  fbsql_fetch_field()  example 


<?php 

fbsql_connect  ($host,  $user,  $password) 
or  die  ("Could  not  connect") ; 

$result  =  fbsql_db_query  ("database",  "select  *  from  table") 
or  die  ("Query  failed"); 

#  get  column  metadata 
$i  =  0; 

while  ($i  <  fbsql_num_f ields  ($result))  { 

echo  "Information  for  column  $i:<BR>\n"; 

$meta  =  fbsql_f etch_f ield  ($result); 
if  (  ! $meta)  { 

echo  "No  information  available<BR>\n" ; 


} 


echo  " 
max_length 
name : 
not_null : 
table : 
type: 

< / P  RE  > " ; 


<PRE> 

:  $meta->max_length 

$meta->name 
$meta->not_null 
$meta->table 
$meta->type 


$i  +  +  ; 


} 

fbsql_f ree_result  ($result); 


?> 


See  also  fbsql_field_seekO- 


f  bsql_fetch_lengths  (php  4  >=  4.0.6) 


Get  the  length  of  each  output  in  a  result 


array  fbsql_fetch_lengths  ([resource  result ]) 


Returns:  An  array  that  corresponds  to  the  lengths  of  each  field  in  the  last  row  fetched  by 
tbsql  fetch  row'j,  or  false  on  error. 

fbsql_fetch_lengths()  stores  the  lengths  of  each  result  column  in  the  last  row  returned  by 
tbsql  fetch  row)),  tbsql_fetch_array  ')  and  fbsql_fetch_objectO  in  an  array,  starting  at  offset  0. 

See  also:  fbsql_fetch_row '). 
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f  bsql_fetch_object  <php  4  >=  4.0.6) 


Fetch  a  result  row  as  an  object 


object  fbsql_fetch_ob ject  (resource  result,  int  [result_type] ) 


Returns  an  object  with  properties  that  correspond  to  the  fetched  row,  or  false  if  there  are  no  more  rows. 

fbsql_fetch_object()  is  similar  to  fbsql_fetch_arrayO,  with  one  difference  -  an  object  is  returned,  instead 
of  an  array.  Indirectly,  that  means  that  you  can  only  access  the  data  by  the  field  names,  and  not  by  their 
offsets  (numbers  are  illegal  property  names). 

The  optional  argument  result_type  is  a  constant  and  can  take  the  following  values: 

FBSQL_ASSOC,  FBSQL_NUM,  and  FBSQL_BOTH. 

Speed-wise,  the  function  is  identical  to  fbsq l_fetc h_array '),  and  almost  as  quick  as  fbsql_fetch_row ') 

(the  difference  is  insignificant). 

Ejemplo  1.  fbsql_fetch_object()  example 


<?php 

fbsql_connect  ($host,  $user,  $password) ; 

$result  =  fbsql_db_query  ("database",  "select  *  from  table"); 
while  ($row  =  fbsql_fetch_ob ject  ($result) )  { 

echo  $row->user_id; 
echo  $row->fullname; 

} 

fbsql_f ree_result  ($result); 

?> 


See  also:  fbsq [_fetc h_array ')  and  fbsql_fetch_row '). 

fbsq  l_f  etchrow  (php  4  >=  4.o.6) 

Get  a  result  row  as  an  enumerated  array 

array  fbsql_fetch_row  (resource  result) 

Returns:  An  array  that  corresponds  to  the  fetched  row,  or  false  if  there  are  no  more  rows. 

fbsql_fetch_row()  fetches  one  row  of  data  from  the  result  associated  with  the  specified  result  identifier. 
The  row  is  returned  as  an  array.  Each  result  column  is  stored  in  an  array  offset,  starting  at  offset  0. 
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Subsequent  call  to  fbsql_fetch_row()  would  return  the  next  row  in  the  result  set,  or  false  if  there  are  no 
more  rows. 

See  also:  thsq  l_fetc  h_array '),  fbsql_fetch_object '),  fbsql_data_seek '),  thsql  fctch  lengths and 
tbsqlresult'). 


f  bsql_f  ield_f  lags  (php  4  >=  4.0.6) 

Get  the  flags  associated  with  the  specified  field  in  a  result 

string  fbsql_f ield_f lags  (resource  result,  int  field_offset) 


fbsql_field_flags()  returns  the  field  flags  of  the  specified  field.  The  flags  are  reported  as  a  single  word  per 
flag  separated  by  a  single  space,  so  that  you  can  split  the  returned  value  using  explode^)- 


f  bsql_f  ield_name  (php  4  >=  4.o.6) 

Get  the  name  of  the  specified  field  in  a  result 

string  fbsql_f ield_name  (resource  result,  int  field_index) 


fbsql_field_name()  returns  the  name  of  the  specified  field  index,  result  must  be  a  valid  result 
identifier  and  field_index  is  the  numerical  offset  of  the  field. 

Nota:  field_index  starts  at  0. 

e.g.  The  index  of  the  third  field  would  actually  be  2,  the  index  of  the  fourth  field  would  be  3  and  so  on. 


Ejemplo  1.  fbsql_field_name()  example 

//  The  users  table  consists  of  three  fields: 

/ /  user_id 

/ /  username 

/ /  password . 

$res  =  fbsql_db_query ( "users " ,  "select  *  from  users",  $link) ; 

echo  fbsql_field_name ($res,  0)  .  "\n"; 

echo  fbsql_field_name ($res,  2); 
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The  above  example  would  produce  the  following  output: 

user_id 

password 


fbsql_field_len  (php4>=4  0  6) 

Returns  the  length  of  the  specified  field 

int  fbsql_f ield_len  (resource  result,  int  field_offset) 

fbsql_field_len()  returns  the  length  of  the  specified  field. 

f  bsql_f  ield_seek  {php  a  >=  4 .0 .6> 

Set  result  pointer  to  a  specihed  held  offset 

bool  fbsql_f ield_seek  (resource  result,  int  field_offset) 

Seeks  to  the  specihed  held  offset.  If  the  next  call  to  fbsql_fetch_held')  doesn’t  include  a  held  offset,  the 
held  offset  specihed  in  fbsql_field_seek()  will  be  returned. 

See  also:  fbsql_fetch_held\). 

f  bsq  l_f  ield_table  <php  4  >=  4.0.6) 

Get  name  of  the  table  the  specihed  held  is  in 

string  fbsql_f ield_table  (resource  result,  int  field_offset) 

Returns  the  name  of  the  table  that  the  specifed  held  is  in. 
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f  bsql_f  ield_type  (php  4  >=  4.0.6) 


Get  the  type  of  the  specified  field  in  a  result 


string  fbsql_f ield_type  (resource  result,  int  field_offset) 


fbsql_field_type()  is  similar  to  the  fbsq[_field_name ')  function.  The  arguments  are  identical,  but  the 
field  type  is  returned  instead.  The  field  type  will  be  one  of  "int",  "real",  "string",  "blob",  and  others  as 
detailed  in  the  FrontBase  documentation  (http://www.frontbase.com/cgi- 
bin/WebObjects/FrontBase.woa/wa/productsPage?currentPage=Documentation). 


Ejemplo  1.  fbsql_field_type()  example 

<?php 

fbsql_connect  ( " localhost " ,  "_SYSTEM", 
fbsql_select_db  ("Wisconsin") ; 

$result  =  fbsql_query  ("SELECT  *  FROM  onek; ") ; 

$fields  =  fbsql_num_f ields  ($result); 

$rows  =  fbsql_num_rows  ($result); 

$i  =  0; 

$table  =  fbsql_f ield_table  ($result,  $i) ; 

echo  "Your  '".Stable."'  table  has  ",$f ields."  fields  and  ",$rows."  records  <BR>" 
echo  "The  table  has  the  following  fields  <BR>"; 
while  ($i  <  $fields)  { 


$type 

=  fbsql_f ield_type 

($result, 

$i)  ; 

$name 

=  fbsql_f ield_name 

(Sresult, 

$i)  ; 

$len 

=  fbsql_f ield_len 

(Sresult, 

$i)  ; 

$f lags 

=  fbsql_f ield_f lags 

(Sresult, 

$i) ; 

echo  $type . "  ",$name."  ",$len."  " . $flags . "<BR>" ; 
$i++; 

} 

fbsql_close ( )  ; 


f  bsq l_f  ree_resu It  (php  4  >=  4.0.6) 


Free  result  memory 


bool  fbsql_free_result  (int  result) 


324 


FrontBase 


fbsql_free_result()  will  free  all  memory  associated  with  the  result  identifier  result. 

fbsql_free_result()  only  needs  to  be  called  if  you  are  concerned  about  how  much  memory  is  being  used 
for  queries  that  return  large  result  sets.  All  associated  result  memory  is  automatically  freed  at  the  end  of 
the  script’s  execution. 


f  bsq  l_i  nsert_id  (php  4  >=  4.0.6) 

Get  the  id  generated  from  the  previous  INSERT  operation 

int  fbsql_insert_id  (resource  [link_identifier]) 


fbsql_insert_id()  returns  the  ID  generated  for  an  column  defined  as  DEFAULT  UNIQUE  by  the 
previous  INSERT  query  using  the  given  link_identifier.  If  link_identifier  isn’t  specified, 
the  last  opened  link  is  assumed. 

fbsql_insert_id()  returns  0  if  the  previous  query  does  not  generate  an  DEFAULT  UNIQUE  value.  If  you 
need  to  save  the  value  for  later,  be  sure  to  call  fbsql_insert_id()  immediately  after  the  query  that 
generates  the  value. 

Nota:  The  value  of  the  FrontBase  SQL  function  last_insert_id  o  always  contains  the  most 
recently  generated  DEFAULT  UNIQUE  value,  and  is  not  reset  between  queries. 


f  bsq  I _l  ist_d  bs  <php  4  >=  4.0.6) 


List  databases  available  on  a  FrontBase  server 


resource  fbsql_list_dbs  (resource  [link_identifier]) 


fbsql_list_dbs()  will  return  a  result  pointer  containing  the  databases  available  from  the  current  fbsql 
daemon.  Use  the  fbsql_tablenameO  function  to  traverse  this  result  pointer. 


Ejemplo  1.  fbsql_list_dbs()  example 

$link  =  fbsql_connect ( ' localhost ' ,  'myname',  'secret' ) ; 
$db_list  =  fbsql_list_dbs ($link) ; 

while  ($row  =  fbsql_fetch_ob ject ($db_list) )  { 
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echo  $row->Database  .  "\n"; 

} 


The  above  example  would  produce  the  following  output: 

databasel 

database2 

database3 


Nota:  The  above  code  would  just  as  easily  work  with  fbsql_fetch_row;)  or  other  similar  functions. 


f  bsql_list_f  ields  (php  4  >=  4.0.6) 


List  FrontBase  result  fields 


resource  fbsql_list_f ields  (string  database_name ,  string  table_name,  resource 
[  link_identifier ] ) 


fbsql_list_fields()  retrieves  information  about  the  given  tablename.  Arguments  are  the  database  name 
and  the  table  name.  A  result  pointer  is  returned  which  can  be  used  with  tbsql_field_l1ags '), 
tbsql  fic Id  lcn '),  fbsql_field_nameO,  and  fbsql_field_type '). 

A  result  identifier  is  a  positive  integer.  The  function  returns  -1  if  a  error  occurs.  A  string  describing  the 
error  will  be  placed  in  $phperrmsg,  and  unless  the  function  was  called  as  @fbsql  ( )  then  this  error 
string  will  also  be  printed  out. 


Ejemplo  1.  fbsql_list_fields()  example 

$link  =  fbsql_connect ( ' localhost ' ,  'myname',  'secret' ) ; 

$fields  =  fbsql_list_f ields ( "databasel "  ,  "tablel",  $link) ; 
$columns  =  fbsql_num_f ields ( $f ields )  ; 

for  ($i  =  0;  $i  <  $columns;  $i++)  { 

echo  fbsql_f ield_name ($f ields,  $i)  .  "\n";; 

} 
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The  above  example  would  produce  the  following  output: 

f ieldl 
f ield2 
f ield3 


f  bsql_list_tables  <php  4  >=  4  o  6> 


List  tables  in  a  FrontBase  database 


resource  fbsql_list_tables  (string  database,  resource  [link_identifier] ) 


fbsql_list_tables()  takes  a  database  name  and  returns  a  result  pointer  much  like  the  tbsql_db_query ') 
function.  The  fbsql_tablenameO  function  should  be  used  to  extract  the  actual  table  names  from  the  result 
pointer. 


f  bsql_next_result  <php  4  >=  4.o.6) 

Move  the  internal  result  pointer  to  the  next  result 

bool  fbsql_next_result  (int  result_id) 


When  sending  more  than  one  SQL  statement  to  the  server  or  executing  a  stored  procedure  with  multiple 
results  will  cause  the  server  to  return  multiple  result  sets.  This  function  will  test  for  additional  results 
available  form  the  server.  If  an  additional  result  set  exists  it  will  free  the  existing  result  set  and  prepare  to 
fetch  the  words  from  the  new  result  set.  The  function  will  return  true  if  an  additional  result  set  was 
available  or  false  otherwise. 

Ejemplo  1.  fbsql_next_result()  example 


<?php 

$link  =  fbsql_connect  ( " localhost " ,  "_SYSTEM",  "secret") ; 
fbsql_select_db ( "MyDB"  ,  Slink) ; 

$SQL  =  "Select  *  from  tablel;  select  *  from  table2;"; 

$rs  =  fbsql_query ($SQL,  $link) ; 
do  { 
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while  ($row  =  fbsql_f etch_row ( $rs ) )  { 

} 

}  while  ( fbsql_next_result ( $rs )  )  ; 
fbsql_f ree_result ($rs)  ; 
fbsql_close  ($link) ; 


fbsql_num_f  ields  (php  4  >=  4.0.6) 

Get  number  of  fields  in  result 

int  fbsql_num_f ields  (resource  result) 

fbsql_num_fields()  returns  the  number  of  fields  in  a  result  set. 

See  also:  fbsq l_db_query '),  fbsql_query\),  fbsq[_fetch_ficld'j.  and  fbsql_num_rows|'). 


f  bsql_num_rows  <php  4  >=  4.o.6) 


Get  number  of  rows  in  result 


int  fbsql_num_rows  (resource  result) 


fbsql_num_rows()  returns  the  number  of  rows  in  a  result  set.  This  command  is  only  valid  for  SELECT 
statements.  To  retrieve  the  number  of  rows  returned  from  a  INSERT,  UPDATE  or  DELETE  query,  use 
fbsql_affected_rows '). 

Ejemplo  1.  fbsql_num_rows()  example 

<?php 

$link  =  fbsql_connect ( " localhost " ,  "username",  "password"); 
fbsql_select_db ( "database"  ,  $link) ; 

$result  =  fbsql_query ( "SELECT  *  FROM  tablel;",  $link)  ; 

$num_rows  =  fbsql_num_rows ( Sresult ) ; 

echo  "$num_rows  Rows\n"; 

?> 
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See  also:  fbsql_affected_rows '),  fbsql_connect '),  fbsql_select_db '),  and  fbsql_query  [). 


f  bsql_pconnect  (php  4  >=  4.o.6) 


Open  a  persistent  connection  to  a  FrontBase  Server 

resource  fbsql_pconnect  ([string  hostname  [,  string  username  [,  string 
password] ] ] ) 


Returns:  A  positive  FrontBase  persistent  link  identifier  on  success,  or  false  on  error. 

fbsql_pconnect()  establishes  a  connection  to  a  FrontBase  server.  The  following  defaults  are  assumed  for 
missing  optional  parameters:  host  =  Tocalhost’,  username  =  ''_SYSTEM"  and  password  =  empty 
password. 

fbsql_pconnect()  acts  very  much  like  fbsql_connect()  with  two  major  differences. 

To  set  Frontbase  server  port  number,  use  fbsql_select_db  ). 

First,  when  connecting,  the  function  would  first  try  to  find  a  (persistent)  link  that’s  already  open  with  the 
same  host,  username  and  password.  If  one  is  found,  an  identifier  for  it  will  be  returned  instead  of  opening 
a  new  connection. 

Second,  the  connection  to  the  SQL  server  will  not  be  closed  when  the  execution  of  the  script  ends. 
Instead,  the  link  will  remain  open  for  future  use. 

This  type  of  links  is  therefore  called  ’persistent’. 


f bsql_query  php  4  >=  4 .0 ,6) 


Send  a  FrontBase  query 


resource  fbsql_query  (string  query  [,  resource  link_identifier]) 


fbsql_query()  sends  a  query  to  the  currently  active  database  on  the  server  that’s  associated  with  the 
specified  link  identifier.  If  link_identifier  isn’t  specified,  the  last  opened  link  is  assumed.  If  no 
link  is  open,  the  function  tries  to  establish  a  link  as  if  fbsql_connect()  was  called  with  no  arguments,  and 
use  it. 

Nota:  The  query  string  shall  always  end  with  a  semicolon. 


329 


FrontBase 


fbsql_query()  returns  true  (non-zero)  or  false  to  indicate  whether  or  not  the  query  succeeded.  A 
return  value  of  true  means  that  the  query  was  legal  and  could  be  executed  by  the  server.  It  does  not 
indicate  anything  about  the  number  of  rows  affected  or  returned.  It  is  perfectly  possible  for  a  query  to 
succeed  but  affect  no  rows  or  return  no  rows. 

The  following  query  is  syntactically  invalid,  so  fbsql_query()  fails  and  returns  false: 

Ejemplo  1.  fbsql_query()  example 

<?php 

$ result  =  fbsql_query  ("SELECT  *  WHERE  1=1") 
or  die  ("Invalid  query"); 

?> 


The  following  query  is  semantically  invalid  if  my_col  is  not  a  column  in  the  table  my_tbl,  so 
fbsql_query()  fails  and  returns  false: 

Ejemplo  2.  fbsql_query()  example 

<?php 

$result  =  fbsql_query  ("SELECT  my_col  FROM  my_tbl") 
or  die  ("Invalid  query"); 

?> 


fbsql_query()  will  also  fail  and  return  false  if  you  don’t  have  permission  to  access  the  table(s) 
referenced  by  the  query. 

Assuming  the  query  succeeds,  you  can  call  fbsql_num_rows  3  to  find  out  how  many  rows  were  returned 
for  a  SELECT  statment  or  fbsql_affected_rows 3  to  find  out  how  many  rows  were  affected  by  a 
DELETE,  INSERT,  REPLACE,  or  UPDATE  statement. 

For  SELECT  statements,  fbsql_query()  returns  a  new  result  identifier  that  you  can  pass  to  fbsql_result'). 

When  you  are  done  with  the  result  set,  you  can  free  the  resources  associated  with  it  by  calling 

thsql  frce  result  ).  Although,  the  memory  will  automatically  be  freed  at  the  end  of  the  script’s  execution. 

See  also:  fbsql_affected_rows  3,  fbsql_db_query  3,  fbsql_free_result(),  fbsql_result3,  fbsql_select_db  3, 
and  fbsql_connect  3- 


fbsql_read_blob  (unknown) 

Read  a  BLOB  from  the  database 

string  fbsql_read_blob  (string  blob_handle,  resource  [ link_identifier ]) 
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Returns:  A  string  containing  the  BLOB  specified  by  blob_handle. 

fbsql_read_blob()  reads  BLOB  data  from  the  database.  If  a  select  statement  contains  BLOB  and/or 
BLOB  columns  FrontBase  will  return  the  data  directly  when  data  is  fetched.  This  default  behavior  can  be 
changed  with  fbsql_set_lob_mode')  so  the  fetch  functions  will  return  handles  to  BLOB  and  CLOB  data. 

If  a  handle  is  fetched  a  user  must  call  fbsql_read_blob()  to  get  the  actual  BLOB  data  from  the  database. 

Ejemplo  1.  fbsql_read_bIob()  example 

<?php 

$link  =  fbsql_pconnect  ( "localhost " ,  "_SYSTEM",  "secret") 
or  die  ("Could  not  connect") ; 

$ sql  =  "SELECT  BLOB_COLUMN  FROM  BLOB_TABLE; " ; 

$rs  =  fbsql_query ($sql,  Slink); 

$row_data  =  fbsql_f etch_row ( $rs ) ; 

//  $row_data[0]  will  now  contain  the  blob  data  for  teh  first  row 
fbsql_f ree_result ($rs)  ; 

$rs  =  fbsql_query ($sql,  $link) ; 
fbsql_set_lob_mode ( $rs,  FBSQL_LOB_HANDLE) ; 

$row_data  =  fbsql_f etch_row ( $rs ) ; 

//  $row_data[0]  will  now  contain  a  handle  to  the  BLOB  data  in  the  first  row 
$blob_data  =  fbsql_read_blob ( $row_data [ 0 ] ) ; 
fbsql_f ree_result ($rs) ; 


?> 


See  also:  fbsql_create_blob '),  Ibsql_read_blob(),  tbsql  read  clob '),  and  fbsql_set_lob_mode(). 


fbsql_read_clob  (unknown) 

Read  a  CLOB  from  the  database 

string  fbsql_read_clob  (string  clob_handle,  resource  [link_identifier]) 


Returns:  A  string  containing  the  CLOB  specified  by  clob_handle. 

fbsql_read_clob()  reads  CLOB  data  from  the  database.  If  a  select  statement  contains  BLOB  and/or 
CLOB  columns  FrontBase  will  return  the  data  directly  when  data  is  fetched.  This  default  behavior  can  be 
changed  with  fbsq[_set_lob_mode  )  so  the  fetch  functions  will  return  handles  to  BLOB  and  CLOB  data. 
If  a  handle  is  fetched  a  user  must  call  fbsql_read_clob()  to  get  the  actual  CLOB  data  from  the  database. 
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Ejemplo  1.  fbsql_read_clob()  example 

<?php 

$link  =  fbsql_pconnect  ( "localhost " ,  "_SYSTEM",  "secret") 
or  die  ("Could  not  connect") ; 

$ sql  =  "SELECT  CLOB_COLUMN  FROM  CLOB_TABLE; " ; 

$rs  =  fbsql_query ($sql,  $link) ; 

$row_data  =  fbsql_f etch_row ( $rs ) ; 

//  $row_data[0]  will  now  contain  the  clob  data  for  teh  first  row 
fbsql_f ree_result ($rs)  ; 

$rs  =  fbsql_query ($sql,  Slink); 
fbsql_set_lob_mode ( $rs,  FBSQL_LOB_HANDLE) ; 

$row_data  =  fbsql_f etch_row ( $rs ) ; 

//  $row_data[0]  will  now  contain  a  handle  to  the  CLOB  data  in  the  first  row 
$clob_data  =  fbsql_read_clob ( $row_data [ 0 ] ) ; 
fbsql_f ree_result ($rs) ; 


?> 


See  also:  fbsql_create_blob(),  fbsql_read_blob'),  fbsql_read_clob(),  and  fbsql_set_lob_mode(). 


f  bsql_result  (php  4  >=  4.0.6) 


Get  result  data 


mixed  fbsql_result  (resource  result,  int  row,  mixed  [field]) 


fbsql_result()  returns  the  contents  of  one  cell  from  a  FrontBase  result  set.  The  field  argument  can  be  the 
field’s  offset,  or  the  field’s  name,  or  the  field’s  table  dot  field’s  name  (tabledname. fieldname).  If  the 
column  name  has  been  aliased  (’select  foo  as  bar  from...’),  use  the  alias  instead  of  the  column  name. 

When  working  on  large  result  sets,  you  should  consider  using  one  of  the  functions  that  fetch  an  entire 
row  (specified  below).  As  these  functions  return  the  contents  of  multiple  cells  in  one  function  call, 
they’re  MUCH  quicker  than  fbsql_result().  Also,  note  that  specifying  a  numeric  offset  for  the  field 
argument  is  much  quicker  than  specifying  a  fieldname  or  tablename. fieldname  argument. 

Calls  to  fbsql_result()  should  not  be  mixed  with  calls  to  other  functions  that  deal  with  the  result  set. 

Recommended  high-performance  alternatives:  fbsql_fetch_row '),  fbsql_fetch_array  [),  and 
fbsql_fetch_object '). 


f  bsql_rollback  (php  4  >=  4 .0 ,6) 


Rollback  a  transaction  to  the  database 
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bool  fbsql_rollback  (resource  [link_identifier ]) 

Returns:  true  on  success,  false  on  failure. 

fbsql_rollback()  ends  the  current  transaction  by  rolling  back  all  statements  issued  since  last  commit. 
This  command  is  only  needed  if  autocommit  is  set  to  false. 

See  also:  fbsql_autocommit ')  and  fbsql_commit ') 


fbsql_set_lob_mode  (unknown) 

Set  the  LOB  retreive  mode  for  a  FrontBase  result  set 


bool  fbsql_set_lob_mode  (resource  result,  string  database_name ) 


Returns:  true  on  success,  false  on  error. 

fbsql_set_lob_mode()  sets  the  mode  for  retreiving  LOB  data  from  the  database.  When  BLOB  and 
CLOB  data  is  stored  in  FrontBase  it  can  be  stored  direct  or  indirect.  Direct  stored  LOB  data  will  allways 
be  fetched  no  matter  the  setting  of  the  lob  mode.  If  the  LOB  data  is  less  than  512  bytes  it  will  all  ways  be 
stored  directly. 

•  FBSQL_LOB_DIRECT  -  LOB  data  is  retreived  directly.  When  data  is  fetched  from  the  database  with 
fbsql_fetch_row'),  and  other  fetch  functions,  all  CLOB  and  BLOB  columns  will  be  returned  as 
ordinary  columns.  This  is  the  default  value  on  a  new  FrontBase  result. 

•  FBSQL_LOB_HANDLE  -  LOB  data  is  retreived  as  handles  to  the  data.  When  data  is  fetched  from 
the  database  with  fbsql_fetch_row  (),  and  other  fetch  functions,  LOB  data  will  be  returned  as  a  handle 
to  the  data  if  the  data  is  stored  indirect  or  the  data  if  it  is  stored  direct.  If  a  handle  is  returned  it  will  be 
a  27  byte  string  formated  as  "@’000000000000000000000000’". 


See  also:  fbsql_create_blob'),  fbsq l_create_c lob fbsql_read_blob '),  and  fbsql_read_clob'). 


f  bsql_select_db  (php  4  >=  4.0.6) 

Select  a  FrontBase  database 

bool  fbsql_select_db  (string  database_name ,  resource  [link_identifier]) 


Returns:  true  on  success,  false  on  error. 
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fbsql_select_db()  sets  the  current  active  database  on  the  server  that’s  associated  with  the  specified  link 
identifier.  If  no  link  identifier  is  specified,  the  last  opened  link  is  assumed.  If  no  link  is  open,  the  function 
will  try  to  establish  a  link  as  if  fbsql_connect ')  was  called,  and  use  it. 

The  client  contacts  FBExec  to  obtain  the  port  number  to  use  for  the  connection  to  the  database.  If  the 
database  name  is  a  number  the  system  will  use  that  as  a  port  number  and  it  will  not  ask  FBExec  for  the 
port  number.  The  FrontBase  server  can  be  stared  as  FRontBase  -FBExec=No  -port=<port  number> 
<database  name>. 

Every  subsequent  call  to  fbsql_query ')  will  be  made  on  the  active  database. 

See  also:  fbsql_connect'),  fbsql  pconiiect'),  and  fbsql_query '). 


f  bsql_start_db  (php  4  >=  4.0.6) 

Start  a  database  on  local  or  remote  server 

bool  fbsql_start_db  (string  database_name ,  resource  [link_identifier]) 

Returns:  true  on  success,  false  on  failure. 

fbsql_start_db() 

See  also:  fbsql_db_status  ')  and  fbsql_stop_db'). 


f bsql_stop_db  php  4  >=  4 .0 .6) 

Stop  a  database  on  local  or  remote  server 

bool  fbsql_stop_db  (string  database_name ,  resource  [link_identifier] ) 

Returns:  true  on  success,  false  on  failure. 

fbsql_stop_db() 

See  also:  fbsql_db_statusQ  and  fbsql_start_db(). 


fbsql_tablename  (unknown) 


Get  table  name  of  field 
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string  fbsql_tablename  (resource  result,  int  i) 


fbsql_tablename()  takes  a  result  pointer  returned  by  the  fbsql_list_tables  ')  function  as  well  as  an  integer 
index  and  returns  the  name  of  a  table.  The  tbsql_num_rows ')  function  may  be  used  to  determine  the 
number  of  tables  in  the  result  pointer. 

Ejemplo  1.  fbsql_tablename()  example 


<?php 

fbsql_connect  ( "localhost " ,  "_SYSTEM", 

$result  =  fbsql_list_tables  ("Wisconsin") ; 

$i  =  0; 

while  ($i  <  fbsql_num_rows  ($result))  { 

$tb_names [ $i ]  =  fbsql_tablename  ($result,  $i) ; 
echo  $tb_names [ $i ]  .  "<BR>"; 

$i  +  +  ; 

} 

?> 


f  bsq  Iwarn  i  ngs  (php  4  >=  4.0.6) 


Enable  or  disable  FrontBase  warnings 


bool  fbsql_warnings  (bool  [OnOff]) 


Returns  true  if  warnings  is  turned  on  otherwise  false. 
fbsql_warnings()  enables  or  disables  FrontBase  warnings. 
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XXV.  Funciones  filePro 


Estas  funciones  permiten  acceso  en  modo  de  solo-lectura  a  datos  guardados  en  bases  de  datos  filePro. 

filePro  es  una  marca  registrada  de  fP  Technologies,  Inc.  Mas  informacion  sobre  filePro  puede 
encontrarse  en  http://www.fptech.com/. 
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filepro  (PHP  3,  PHP  4  >=  4.0.0) 

lee  y  verifica  el  fichero  de  mapeo 

bool  filepro  (string  directory) 

Lee  y  verifica  el  fichero  de  mapeo,  guardando  la  relacion  de  campos  e  informacion. 

Ningun  bloqueo  es  realizado,  por  ello,  no  se  deberia  modificar  la  base  de  datos  filePro  cuando  puede  ser 
abierta  con  PHP. 

f ilepro_f ieldname  (php 3,  php 4 >=  4 .o ,<» 

obtiene  el  nombre  de  un  campo 

string  filepro_f ieldname  (int  field_number ) 

Devuelve  el  nombre  del  campo  correspondiente  a  field_number. 

f  ilepro_f  ieldtype  (php  3,  php  4  >=  4.o.o) 

obtiene  el  tipo  de  campo 

string  filepro_f ieldtype  (int  field_number) 

Devuelve  el  tipo  de  campo  del  campo  correspondiente  a  field_number. 

f ilepro_f ieldwidth  (php  3  php  4  >=  4.o.o) 

obtiene  la  anchura  de  un  campo 

int  filepro_f ieldwidth  (int  field_number) 

Devuelve  la  anchura  de  el  campo  correspondiente  a  field_number. 
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f ilepro_retrieve  (php 3,  php 4 >=  4.o.o) 

extrae  informacion  de  una  base  de  datos  filePro 

string  f ilepro_retrieve  (int  row_number ,  int  field_number ) 

Devuelve  la  informacion  de  la  base  de  datos  contenida  en  la  localizacion  especificada. 

f ilepro_f ieldcount  <php 3,  php 4 >=  4.o.o) 

encuentra  cuantos  campos  existen  en  una  base  de  datos  filePro 

int  filepro_f ieldcount (void) ; 

Devuelve  el  numero  de  campos  (columnas)  existentes  en  la  base  de  datos  filePro  abierta. 

Ver  tambien  fileproO- 

f ilepro_rowcount  (php 3  php 4 >=  4 o o> 

encuentra  cuantas  filas  existen  en  una  base  de  datos  filePro 

int  f ilepro_rowcount (void)  ; 

Devuelve  el  numero  de  filas  (entradas)  existentes  en  la  base  de  datos  filePro  abierta. 

Ver  tambien  fileproO. 
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basename  (PHP  3,  PHP  4  >=  4.0.0) 


Devuelve  la  parte  del  path  correspondiente  al  nombre  del  fichero 


string  basename  (string  path) 


Dada  una  cadena  (string)  que  contiene  el  path  de  un  fichero,  esta  funcion  devuelve  el  nombre  base  del 
fichero. 

En  Windows,  tanto  la  barra  (/)  como  la  barra  inversa  (\)  pueden  usarse  como  caracter  separador  en  el 
path.  En  otros  entornos,  se  usa  la  barra  directa  (/). 


Ejemplo  1.  Ejemplo  de  basenamef) 

$path  =  " /home/httpd/html/index . php3 " ; 

$file  =  basename ( $path) ;  //  $file  toraa  el  valor  "index. php3" 


Ver  tambien:  dirname  ) 


chgrp  (PHP  3,  PHP  4  >=4.0.0) 

Cambia  el  grupo  de  un  fichero 

int  chgrp  (string  filename ,  mixed  group) 


Trata  de  cambiar  el  grupo  al  que  pertenece  el  fichero  filename  al  grupo  group.  Solo  el  superusuario 
puede  cambiar  el  grupo  de  un  fichero  arbitrariamente;  otros  usuarios  pueden  cambiar  el  grupo  del  fichero 
a  cualquier  grupo  del  cual  el  usuario  sea  miembro. 

Devuelve  true  en  caso  de  exito;  en  otro  caso  devuelve  false. 

En  Windows,  no  hace  nada  y  devuelve  true. 

Ver  tambien  chown  )  y  chmod '). 


chmod  (PHP  3,  PHP  4  >=  4.0.0) 

Cambia  permisos  de  un  fichero 
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int  chmod  (string  filename,  int  mode) 


Trata  de  cambiar  los  permisos  del  fichero  especificado  por  filename  a  los  permisos  dados  por  mode. 

Cuidado  que  mode  no  es  asumido  de  forma  automatica  como  un  valor  octal.  Para  asegurar  que  se  hace  la 
operation  esperada  necesitas  anteponer  un  cero  (0)  como  prefijo  del  parametro  mode: 

chmod (  " /somedir /some file " ,  755  );  //  decimal;  probablemente  incorrecto 

chmod (  "/somedir/somefile" ,  0755  );  //  octal;  valor  correcto  de  mode 


Devuelve  true  en  caso  de  exito  y  false  en  otro  caso. 
Ver  tambien  chown  )  y  chgrp' ')■ 


chown  (PHP  3,  PHP  4  >=  4.0.0) 

Cambia  el  propietario  de  un  fichero 

int  chown  (string  filename,  mixed  user) 

Trata  de  cambiar  el  propietario  del  fichero  filename  al  usuario  user.  Solo  el  superusuario  puede  cambiar 
el  propietario  de  un  fichero. 

Devuelve  true  en  caso  de  exito;  en  otro  caso  devuelve  false. 

Nota:  En  Windows,  no  hace  nada  y  devuelve  true. 


Ver  tambien  chown()  y  chmod '). 


clearstatcache  (PHP  3,  PHP  4  >=  4.0.0) 


Limpia  la  cache  de  estado  de  un  fichero 


void  clearstatcache (void) ; 


341 


Filesystem 


Invocar  la  llamada  del  sistema  stat  o  lstat  es  bastante  costoso  en  la  mayorfa  de  los  sistemas.  Por  lo  tanto, 
el  resultado  de  la  ultima  llamada  a  cualquiera  de  las  funciones  de  estado  (listadas  abajo)  es  guardado 
para  usarlo  en  la  proxima  llamada  de  este  tipo  empleando  el  mismo  nombre  de  fichero.  Si  deseas  forzar 
un  nuevo  chequeo  del  estado  del  fichero,  por  ejemplo  si  el  fichero  esta  siendo  chequeado  muchas  veces  y 
puede  cambiar  o  desaparecer,  usa  esta  funcion  para  borrar  los  resultados  almacenados  en  memoria  de  la 
ultima  llamada. 

Este  valor  solo  es  cacheado  durante  el  tiempo  de  vida  de  una  peticion  simple. 

Entre  las  funciones  afectadas  se  incluyen  stat  ),  lstat"),  file_exists'),  is_writeable)),  is_readable  ), 
is_executable)),  is_file)),  is  dir  ),  is_link)),  filectime'),  fileatime'),  filemtime3,  fileinode  ),  filegroup)), 
fileowner)),  filesize)),  filetype),  y  fileperms)). 


copy  (PHP  3,  PHP  4  >=  4.0.0) 


Copia  un  fichero 


int  copy  (string  source,  string  dest) 


Hace  una  copia  de  un  fichero.  Devuelve  true  si  la  copia  tiene  exito,  y  false  en  otro  caso. 

Ejemplo  1.  Ejemplo  de  copy() 

if  ( ! copy ($file,  $file . ' .bak' ) )  { 

print (" failed  to  copy  $f ile . . . <br>\n" ) ; 

} 


Ver  tambien:  rename)). 

delete  (unknown) 

Una  entrada  manual  inutil 

void  delete  (string  file) 

Esto  es  una  entrada  manual  inutil  para  satisfacer  a  esas  personas  que  estan  buscando  unlink!)  o  unset))  en 
el  lugar  equivocado. 

Ver  tambien:  unlink  )  para  borrar  ficheros,  unset!)  para  borrar  variables. 
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dirname  (PHP  3,  PHP  4  >=  4.0.0) 


Devuelve  la  parte  del  path  correspondiente  al  directorio 


string  dirname  (string  path) 


Dada  una  cadena  (string)  conteniendo  el  path  a  un  fichero,  esta  funcion  devolvera  el  nombre  del 
directorio. 

En  Windows,  tanto  la  barra  (/)  como  la  barra  inversa  (\)  son  usadas  como  separadores  de  caracteres.  En 
otros  entornos,  debe  usarse  la  barra  directa  (/). 


Ejemplo  1.  Ejemplo  de  dirname() 

$path  =  " /etc/passwd" ; 

$file  =  dirname ( $path) ;  //  $file  toraa  el  valor  "/etc" 


Ver  tambien:  basenameO 


diskfreespace  (PHP  3>=  3.0.7,  PHP  4  >=  4.0.0) 

Devuelve  el  espacio  disponible  en  un  directorio 

float  diskfreespace  (string  directory ) 


Dada  una  cadena  (string)  conteniendo  el  nombre  de  un  directorio,  esta  funcion  devolvera  el  numero  de 
bytes  disponibles  en  el  disco  correspondiente. 


Ejemplo  1.  Ejemplo  de  diskfreespace() 

$df  =  diskf reespace ( " / " ) ;  //  $df  contiene  el  numero  de  bytes 

//  disponibles  en  "/" 
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fclose  (PHP  3,  PHP  4  >=  4.0.0) 

Cierra  el  apuntador  a  un  fichero  abierto 

int  fclose  (int  fp) 


Se  cierra  el  fichero  apuntado  por  fp. 

Devuelve  true  en  caso  de  exito  y  false  en  caso  de  fallo. 

El  apuntador  al  fichero  debe  ser  valido  y  debe  apuntarse  a  un  fichero  abierto  con  exito  con  fopen ')  o  con 
fsockopen)). 


feof  (PHP  3,  PHP  4  >=4.0.0) 

Verifica  si  el  apuntador  a  un  fichero  esta  al  final  del  fichero  (end-of-file) 

int  feof  (int  fp) 

Devuelve  true  si  el  apuntador  del  fichero  esta  en  EOF  o  si  ocurre  un  error;  en  otro  caso  devuelve  false. 

The  file  pointer  must  be  valid,  and  must  point  to  a  file  El  apuntador  al  fichero  debe  ser  valido,  y  debe 
apuntar  a  un  fichero  abierto  con  exito  por  fopen'),  popen)),  o  fsockopen )). 


fgetc  (PHP  3,  PHP  4  >=  4.0.0) 

Obtiene  un  caracter  del  fichero  apuntado 

string  fgetc  (int  fp) 

Devuelve  una  cadena  (string)  conteniendo  un  simple  caracter  leido  del  fichero  apuntado  por  fp.  Devuelve 
false  para  EOF  (como  hace  feof')). 

El  apuntador  al  fichero  debe  ser  valido,  y  debe  apuntar  a  un  fichero  abierto  con  exito  por  fopen)), 
popen)),  o  fsockopen )). 

Ver  tambien  fread),  fopen)),  popen)),  fsockopen)),  y  fgets)). 
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Obtiene  una  lfnea  del  fichero  apuntado  y  extrae  los  campos  CSV 

array  fgetcsv  (int  fp,  int  length,  string  [delimiter]) 


Parecida  a  fgets()  excepto  que  fgetcsv!)  parsea  la  lfnea  que  lee  buscando  campos  en  formato  CSV  y 
devuelve  un  array  conteniendo  los  campos  leidos.  El  delimitador  de  campo  es  una  coma,  a  menos  que  se 
especifique  otro  delimitador  con  el  tercer  parametro  opcional. 

fp  debe  ser  un  apuntador  valido  a  un  fichero  abierto  con  exito  por  to  pen '),  popcn o  fsockopen () 

la  longitud  debe  ser  mayor  que  la  lfnea  mas  larga  que  pueda  encontrarse  en  le  fichero  CSV  (permitiendo 
arrastrar  caracteres  de  fin  de  lfnea) 

fgetcsv()  devuelve  false  en  caso  de  error,  incluyendo  el  fin  de  fichero. 

NOTA:  Una  lfnea  en  bianco  en  un  fichero  CSV  se  devuelve  como  un  array  que  contiene  un  unico  campo 
nulo,  y  esto  no  sera  tratado  como  un  error. 

Ejemplo  1.  Ejemplo  de  fgetcsv()  -  Leer  e  imprimir  el  contenido  completo  de  un  fichero  CSV 

$row  =  1; 

$fp  =  fopen  ( "test . csv" , "r" ) ; 

while  ($data  =  fgetcsv  ($fp,  1000,  { 

$num  =  count  ($data) ; 

print  "<p>  $nura  fields  in  line  $row:  <br>"; 

$row++; 

for  ($c=0;  $c<$num;  $c++)  { 

print  $data[$c]  .  "<br>"; 


} 

fclose  ($fp) ; 


fgets  (PHP  3,  PHP  4  >=  4.0.0) 

Obtiene  una  lfnea  del  fichero  apuntado 

string  fgets  (int  fp,  int  length) 


Devuelve  una  cadena  de  como  mucho  length  -  1  bytes  leidos  del  fichero  apuntado  por  fp.  La  lectura 
acaba  cuando  son  leidos  length  -  1  bytes,  cuando  se  llega  a  una  nueva  lfnea  (el  caracter  de  nueva  lfnea  se 
incluye  en  el  valor  devuelto),  o  cuando  se  llega  a  un  EOF  (lo  que  ocurra  primero). 

Si  ocurre  un  error,  devuelve  false. 
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Fallos  Comunes: 

Los  que  hayan  usado  la  semantica  de  ’C’  de  la  funcion  fgets  deben  darse  cuenta  de  la  diferencia  que  hay 
en  como  el  EOF  es  devuelto  por  esta  funcion. 

El  apuntador  al  fichero  debe  ser  valido,  y  debe  apuntar  a  un  fichero  abierto  con  exito  con  fopcn )), 
popen)),  o  fsockopen '). 

A  continuation  un  ejemplo  sencillo: 

Ejemplo  1.  Leyendo  un  fichero  lfnea  por  lfnea 

$fd  =  fopen  ( " /tmp/inputf ile . txt " ,  "r"); 

while  (!feof($fd))  { 

$buffer  =  fgets ($fd,  4096) ; 
echo  $buffer; 

} 

fclose  ( $  f d) ; 


Ver  tambien  fread),  fopen'),  popen'),  fgetc)),  y  fsockopen'). 

fgetss  (PHP  3,  PHP  4  >=  4.0.0) 

Obtiene  una  lfnea  del  fichero  apuntado  y  quita  las  etiquetas  HTML 

string  fgetss  (int  fp,  int  length,  string  [allowable_tags]) 

Identica  a  fgets  '),  excepto  que  fgetss  trata  de  quitar  cualquier  etiqueta  HTML  y  PHP  del  texto  que  lee. 
Se  puede  utilizar  el  tercer  parametro  opcional  para  especificar  etiquetas  que  no  deben  de  quitarse. 

Nota:  allowable_tags  fue  anadido  en  PHP  3.0.13,  PHP4B3. 


Ver  tambien  fgets)),  fopen)),  fsockopen)),  popen '),  y  strip_tags '). 


file  (PHP  3,  PHP  4  >=4.0.0) 

lee  un  fichero  completo  hacia  un  array 

array  file  (string  filename  [,  int  use_include_path] ) 
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Identica  a  readfile  '),  excepto  que  file()  devuelve  el  fichero  en  un  array.  Cada  elemento  del  array 
corresponde  a  una  lmea  del  fichero,  con  el  caracter  de  nueva  lfnea  incluido. 

Se  puede  utilizar  el  segundo  parametro  opcional  y  ponerle  el  valor  "1",  si  tambien  se  quiere  buscar  el 
fichero  en  el  include_path 

Ver  tambien  readfile  '),  fopen),  y  popen  '). 


file_exists  (PHP  3,  PHP  4  >=  4.0.0) 


Verifica  si  un  fichero  existe 


int  file_exists  (string  filename) 


Devuelve  true  si  el  fichero  especificado  por  filename  existe;  y  false  en  otro  caso. 
El  resultado  de  esta  funcion  es  cacheado.  Ver  clearstatcacheC)  para  mas  detalles. 


fileatime  (PHP  3,  PHP  4  >=  4.0.0) 

Obtiene  la  ultima  fecha  de  acceso  a  un  fichero 

int  fileatime  (string  filename) 

Devuelve  la  fecha  a  la  que  el  fichero  fue  accedido  por  ultima  vez,  o  false  en  caso  de  error. 
Los  resultados  de  esta  funcion  son  cacheados.  Ver  clearstatcache ')  para  mas  detalles. 


filectime  (PHP  3,  PHP  4  >=  4.0.0) 

Obtiene  la  fecha  de  cambio  del  inode  del  fichero 

int  filectime  (string  filename) 

Devuelve  el  momento  en  el  que  el  fichero  fue  cambiado  por  ultima  vez,  o  false  en  caso  de  error. 
Los  resultados  de  esta  funcion  son  cacheados.  Ver  clearstatcacheO  para  mas  detalles. 
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filegroup  (PHP  3,  PHP  4  >=  4.0.0) 

Obtiene  el  grupo  de  un  fichero 

int  filegroup  (string  filename) 

Devuelve  el  identificador  (ID)  de  grupo  del  propietario  del  fichero,  o  false  en  caso  de  un  error.  El  ID 
del  grupo  es  devuelto  en  formato  numerico,  usar  posix_getgrgid ')  para  obtener  el  nombre  del  grupo. 

Los  resultados  de  esta  funcion  son  cacheados.  Ver  clearstatcache ')  para  mas  detalles. 

fileinode  (PHP  3,  PHP  4  >=4.0.0) 

Obtiene  el  inode  del  fichero 

int  fileinode  (string  filename) 

Devuelve  el  numero  de  inode  del  fichero,  o  false  en  caso  de  un  error. 

Los  resultados  de  esta  funcion  son  cacheados.  Ver  clearstatcache))  para  mas  detalles. 

filemtime  (PHP  3,  PHP  4  >=4.0.0) 

Obtiene  la  fecha  de  modification  del  fichero 

int  filemtime  (string  filename) 

Devuelve  el  momento  en  el  que  el  fichero  fue  modificado  por  ultima  vez,  o  false  en  caso  de  un  error. 
Los  resultados  de  esta  funcion  son  cacheados.  Ver  clearstatcache))  para  mas  detalles. 

fileowner  (PHP  3,  PHP  4  >=4.0.0) 

Obtiene  el  propietario  del  fichero 

int  fileowner  (string  filename) 
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Devuelve  el  identificador  (ID)  de  usuario  del  propietario  del  fichero,  o  false  en  caso  de  error.  El  ID  de 
usuario  se  devuelve  en  formato  numerico,  usar  posix_getpwuid  ')  para  obtener  el  nombre  del  usuario. 

Los  resultados  de  esta  funcion  son  cacheados.  Ver  clearstatcache ')  para  mas  detalles. 


fileperms  (PHP  3,  PHP  4  >=  4.0.0) 

Obtiene  los  permisos  del  fichero 

int  fileperms  (string  filename ) 

Devuelve  los  permisos  del  fichero,  o  false  en  caso  de  error. 

Los  resultados  de  esta  funcion  son  cacheados.  Ver  clearstatcache  ()  para  mas  detalles. 


filesize  (PHP  3,  PHP  4  >=4.0.0) 

Obtiene  el  tamano  del  fichero 

int  filesize  (string  filename ) 

Devuelve  el  tamano  del  fichero,  o  false  en  caso  de  error. 

Los  resultados  de  esta  funcion  son  cacheados.  Ver  clearstatcache  3  para  mas  detalles. 


filetype  (PHP  3,  PHP  4  >=  4.0.0) 

Obtiene  el  tipo  de  fichero 

string  filetype  (string  filename) 

Devuelve  el  tipo  de  fichero.  Valores  posibles  son  fifo,  char,  dir,  block,  link,  file,  y  unknown. 
Devuelve  false  si  ocurre  un  error. 

Los  resultados  de  esta  funcion  son  cacheados.  Ver  clearstatcache  3  para  mas  detalles. 
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flock 


(PHP  3>=  3.0.7,  PHP  4  >=  4.0.0) 


Bloqueo  de  ficheros  portable  y  asesorado 


bool  flock  (int  fp,  int  operation) 


PHP  soporta  un  metodo  portable  de  bloquear  ficheros  completos  de  manera  asesorada  (lo  que  significa 
que  todos  los  programas  que  acceden  tienen  que  usar  el  mismo  modo  de  bloqueo  o  este  no  funcionara). 

flock()  opera  sobre  fp  el  cual  debe  ser  un  apuntador  a  un  fichero  abierto.  operation  toma  uno  de  los 
siguientes  valores: 


•  Para  que  adquiera  un  bloqueo  compartido  (lectura),  fija  operation  a  1. 

•  Para  adquirir  un  bloqueo  exclusivo  (escritura),  fija  operation  a  2. 

•  Para  liberal'  un  bloqueo  (compartido  o  exclusivo),  fija  operation  a  3. 

•  Si  no  quieres  que  flock()  bloquee  mientras  esta  activado,  suma  4  al  valor  de  operation. 


flock()  permite  establece  un  modelo  simple  de  lectura/escritura  el  cual  puede  usarse  en  practicamente 
cualquier  plataforma  (incluyendo  la  mayoria  de  sistemas  Unix  e  incluso  Windows). 

flock()  devuelve  true  en  caso  de  exito  y  false  en  caso  de  error  (ej.  cuando  no  se  puede  establecer  un 
bloqueo). 


fopen 


(PHP  3,  PHP  4  >=4.0.0) 


Abre  un  fichero  o  una  URL 


int  fopen  (string  filename,  string  mode,  int  [use_include_path] ) 


Si  filename  comienza  con  "http://"  (no  es  sensible  a  mayusculas),  se  abre  una  conexion  HTTP  1.0 
hacia  el  servidor  especificado  y  se  devuelve  un  apuntador  de  fichero  al  comienzo  del  texto  de  respuesta. 

No  maneja  redirecciones  HTTP,  por  eso  se  debe  incluir  una  barra  final  cuando  se  trata  de  directories. 

Si  filename  comienza  con  "ftp://"  (no  es  sensible  a  mayusculas),  se  abre  una  conexion  ftp  hacia  el 
servidor  especificado  y  se  devuelve  un  apuntador  al  fichero  requerido.  Si  el  servidor  no  soporta  ftp  en 
modo  pasivo,  esto  fallara.  Se  pueden  abrir  fichero  via  ftp  para  leer  o  para  escribir  (pero  no  ambas  cosas 
simultaneamente) . 

Si  filename  no  comienza  con  nada  de  lo  anterior,  el  fichero  se  abre  del  sistema  de  ficheros,  y  se 
devuelve  un  apuntador  al  fichero  abierto. 

Si  el  abrir  el  fichero  falla,  la  funcion  devuelve  false. 
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mode  puede  ser  cualquiera  de  lo  siguiente: 

•  ’r’  -  Abre  para  solo  lectura;  situa  el  apuntador  del  fichero  al  comienzo  del  mismo. 

•  ’r+’  -  Abre  para  lectura  y  escritura;  situa  el  apuntador  del  fichero  al  comienzo  del  fichero. 

•  ’w’  -  Abre  para  solo  escritura;  situa  el  apuntador  del  fichero  al  comienzo  del  fichero  y  trunca  el 
fichero  con  longitud  cero.  Si  el  fichero  no  existe,  trata  de  crearlo. 

•  ’w+’  -  Abre  el  fichero  para  lectura  y  escritura;  situa  el  apuntador  del  fichero  al  comienzo  del  fichero  y 
trunca  el  fichero  con  longitud  cero.  Si  el  fichero  no  existe,  trata  de  crearlo. 

•  ’a’  -  Abre  solo  para  escribir  (anadir);  situa  el  apuntador  del  fichero  al  final  del  mismo.  Si  el  fichero  no 
existe,  trata  de  crearlo. 

•  ’a+’  -  Abre  para  lectura  y  escritura  (anadiendo);  situa  el  apuntador  del  fichero  al  final  del  mismo.  Si  el 
fichero  no  existe,  trata  de  crearlo. 

Ademas,  mode  puede  contener  la  letra  ’b’.  Esto  es  util  para  sistemas  que  diferencian  entre  ficheros 

binarios  y  de  texto  (ej.  es  inutil  en  Unix).  Si  no  se  necesita,  sera  ignorado. 

Puede  usarse  el  tercer  parametro  opcional  y  fijarlo  a  "1",  si  tambien  se  quiere  buscar  el  fichero  en  el 

include_path 


Ejemplo  1.  Ejemplo  de  fopen()() 

$fp  =  f open (" /home/ rasmus/file . txt "  ,  "r"); 

$fp  =  f open ( "http :/ /www . php . net /"  ,  "r"); 

$fp  =  f open (" ftp : //user : passwordSexample . com/ " ,  "w"); 


Si  experimentas  problemas  a  la  hora  de  leer  y  escribir  a  ficheros  y  estas  usando  la  version  de  PHP  como 
modulo  para  el  servidor,  recuerda  que  debes  asegurar  que  los  ficheros  y  directorios  que  estas  usando  son 
accesibles  al  proceso  servidor. 

En  la  plataforma  Windows,  ten  cuidado  de  escribir  correctamente  las  barras  invertidas  en  el  path  del 
fichero  (poniendolas  dobles),  o  usa  barras  directas. 

$fp  =  f open ( "c : \ \data\\info . txt " ,  "r"); 


Ver  tambien  fclose'),  fsockopen '),  y  popen  ). 


fpassthru  (PHP  3,  PHP  4  >=4.0.0) 

Saca  todos  los  datos  restantes  del  fichero  apuntado 

int  fpassthru  (int  fp) 
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Lee  hasta  el  EOF  del  fichero  apuntado  y  escribe  los  resultados  a  la  salida  estandar  (stdout). 

Si  ocurre  un  error,  fpassthru()  devuelve  false. 

El  apuntador  al  fichero  debe  ser  valido,  y  debe  apuntar  a  un  fichero  abierto  con  exito  por  fopen)), 
popen),  o  fsockopen).  El  fichero  se  cierra  cuando  fpassthru()  termina  de  leerlo  (dejando  fp  sin 
ninguna  utilidad). 

Si  solo  quieres  volcar  el  contenido  de  un  fichero  a  stdout  puedes  If  you  just  want  to  dump  the  contents  of 
a  file  to  stdout  you  may  usar  la  funcion  readfile'),  la  cual  te  libra  de  la  llamada  a  fopen 

Ver  tambien  readfile  '),  fopen  '),  popen  '),  y  fsockopen  ') 


fputs  (PHP  3,  PHP  4  >=  4.0.0) 

Escribe  en  el  fichero  apuntado 

int  fputs  (int  fp,  string  str,  int  [length] ) 


fputs()  es  un  alias  de  fwrite  3,  y  es  identico  a  el  en  todo.  Notar  que  el  parametro  length  es  opcional  y 
si  no  se  pone  la  cadena  entera  sera  escrita. 


fread  (PHP  3,  PHP  4  >=  4.0.0) 


Lee  ficheros  en  plan  binario 


string  fread  (int  fp,  int  length) 


freadf)  lee  hasta  length  bytes  del  apuntador  de  fichero  referenciado  por  fp.  La  lectura  acaba  cuando 
length  bytes  se  han  leido  o  se  alcanza  EOF,  lo  que  ocurra  primero. 


/ /  Mete  el  contenido  de  un  fichero  en  una  cadena 
$filename  =  " /usr/local/something . txt " ; 

$fd  =  fopen  ($filename,  "r"); 

$contents  =  fread  ($fd,  filesize  ($filename) ) ; 
fclose  ($fd) ; 


Ver  tambien  fwrite  (),  fopen '),  fsockopen)),  popen)),  fgets)),  fgetss  3,  file)),  y  fpassthru  [). 
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fseek  (PHP  3,  PHP  4  >=  4.0.0) 

Situa  el  apuntador  a  un  fichero 

int  fseek  (int  fp,  int  offset) 


Fija  el  indicador  de  position  del  fichero  referenciado  por  fp  a  tantos  bytes  como  indica  offset.  Es 
equivalente  a  la  llamada  (en  C)  fseek  (fp,  offset,  SEEK_SET). 

Si  va  bien,  devuelve  0;  en  otro  caso,  devuelve  -1.  Tener  en  cuenta  que  situarse  mas  alia  de  EOF  no  se 
considera  un  error. 

No  puede  usarse  sobre  apuntadores  de  ficheros  devueltos  por  to  pen ')  si  usan  los  formatos  "http://"  or 
"ftp://". 

Ver  tambien  ftell  /)  y  rewind/). 


ftell  (PHP  3,  PHP  4  >=4.0.0) 

Pregunta  por  la  position  del  apuntador  de  lectura/escritura  de  un  fichero 

int  ftell  (int  fp) 


Devuelve  la  position  del  apuntador  de  fichero  referenciado  por  fp;  es  decir,  la  distancia  en  la  secuencia 
del  fichero. 

Si  ocurre  un  error,  devuelve  false. 

El  apuntador  al  fichero  debe  ser  valido,  y  debe  referirse  a  The  file  pointer  must  be  valid,  and  must  point 
to  a  file  un  fichero  abierto  con  exito  por  to  pen /)  o  popen 

Ver  tambien  fopen '),  popen/),  fseek/)  y  rewind/). 


fwrite  (PHP  3,  PHP  4  >=  4.0.0) 

Escribe  ficheros  en  plan  binario 

int  fwrite  (int  fp,  string  string,  int  [length]) 
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fwrite()  escribe  el  contenido  de  string  al  fichero  apuntado  por  fp.  Si  se  da  el  argumento  length,  la 
escritura  acaba  antes  de  que  length  bytes  sean  escritos  o  se  alcance  el  final  de  string,  lo  que  ocurra 
primero. 

Tener  en  cuenta  que  si  se  da  el  argumento  length,  entonces  la  opcion  de  configuration 
magic_quotes_runtime  sera  ignorada  y  los  caracteres  de  barra  no  se  quitaran  de  la  cadena  string. 

Ver  tambien  tread  '),  fopen  '),  fsockopen '),  popenQ,  y  fputsj). 


set_f  ile_buffer  (php  3>=  3.0.8,  php  4 ) 

Fija  el  buffer  de  fichero  del  fichero  apuntado 

int  fwrite  (int  fp,  int  buffer) 


set_file_buffer()  fija  el  buffer  para  operaciones  de  escritura  en  el  apuntador  de  fichero  fp  con  buffer 
bytes.  Si  buffer  es  0  entonces  las  operaciones  de  escritura  no  usan  un  buffer  intermedio. 

La  funcion  devuelve  0  en  caso  de  exito,  o  EOF  si  la  petition  no  se  puede  realizar. 

Tener  en  cuenta  que  por  defecto  cualquier  fopen  hace  una  llamada  a  set  fi  [e  buftcr  de  8K. 

Ver  tambien  fopen')- 


is_dir  (PHP  3,  PHP  4  >=  4.0.0) 

Dice  si  el  fichero  nombrado  es  un  directorio 

bool  is_dir  (string  filename) 

Devuelve  true  si  el  nombre  del  fichero  existe  y  es  un  directorio. 

Los  resultados  de  esta  funcion  son  cacheados.  Ver  clearstatcache  )  para  mas  detalles. 
Ver  tambien  is_file  ')  y  is_link\). 


is_executable  (PHP  3,  PHP  4  >=4.0.0) 

Dice  si  el  fichero  nombrado  es  ejecutable 

bool  is_executable  (string  filename) 
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Devuelve  true  si  el  fichero  indicado  existe  y  es  ejecutable. 

Los  resultados  de  esta  funcion  son  cacheados.  Ver  clearstatcache ')  para  mas  detalles. 
Ver  tambien  is_file')  y  is_link')- 

is_file  (PHP  3,  PHP  4  >=  4.0.0) 

Dice  si  el  fichero  nombrado  es  un  fichero  regular 

bool  is_file  (string  filename ) 

Devuelve  true  si  el  fichero  nombrado  existe  y  es  un  fichero  regular. 

Los  resultados  de  esta  funcion  son  cacheados.  Ver  clearstatcache  [)  para  mas  detalles. 
Ver  tambien  is_dir ')  y  is_link  ). 

isjink  (PHP  3,  PHP  4  >=  4.0.0) 

Dice  si  el  fichero  indicado  es  un  enlace  simbolico 

bool  is_link  (string  filename) 

Devuelve  true  si  el  fichero  indicado  existe  y  es  un  enlace  simbolico. 

Los  resultados  de  esta  funcion  son  cacheados.  Ver  clearstatcache  ()  para  mas  detalles. 
Ver  tambien  is_dir()  y  is_file'). 

is_readable  (PHP  3,  PHP  4  >=  4.0.0) 

Dice  si  el  fichero  indicado  se  puede  leer 

bool  is_readable  (string  filename ) 

Devuelve  true  si  el  fichero  indicado  existe  y  se  puede  leer. 
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Recuerda  que  PHP  puede  acceder  al  fichero  con  el  identificador  de  usuario  con  el  que  el  servidor  web  se 
ejecuta  (a  menudo  ’nobody’).  No  se  tienen  en  cuenta  las  limitaciones  de  modos  seguros. 

Los  resultados  de  esta  funcion  son  cacheados.  Ver  clearstatcache  )  para  mas  detalles. 

Ver  tambien  is_writeable)). 


is_writeable  (PHP  3,  PHP  4  >=4.0.0) 

Dice  si  se  puede  escribir  en  el  fichero  indicado 

bool  is_writeable  (string  filename) 


Devuelve  true  si  el  fichero  indicado  existe  y  se  puede  escribir  en  el.  El  argumento  filename  puede  ser  el 
nombre  de  un  directorio,  lo  que  permite  verificar  si  un  directorio  tiene  permiso  de  escritura. 

Recuerda  que  PHP  puede  acceder  al  fichero  con  el  identificador  de  usuario  con  el  que  el  servidor  web  se 
ejecuta  (a  menudo  ’nobody’).  No  se  tienen  en  cuenta  las  limitaciones  de  modos  seguros. 

Los  resultados  de  esta  funcion  son  cacheados.  Ver  clearstatcache))  para  mas  detalles. 

Ver  tambien  is_readable '). 


link  (PHP  3,  PHP  4  >=4.0.0) 

Crea  un  enlace  fuerte 

int  link  (string  target,  string  link) 

link()  crea  un  enlace  fuerte. 

Ver  tambien  symlink')  para  crear  enlaces  debiles,  y  read  I  ink  (junto  con  linkinfo)). 

linkinfo  (PHP  3,  PHP  4  >=4.0.0) 

Consigue  informacion  sobre  un  enlace 

int  linkinfo  (string  path ) 
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linkinfo()  da  el  campo  st_dev  de  la  extructura  stat  de  UNIX  C  devuelto  por  la  llamada  al  sistema  lstat. 
Esta  funcion  se  usa  para  verificar  si  un  enlace  (apuntado  por  path )  existe  realmente  (usando  el  mismo 
metodo  que  la  macro  S_ISLNK  definida  en  stat.h).  Devuelve  0  o  false  en  caso  de  error. 

Ver  tambien  symlink^),  link'),  y  read  I  ink  ). 


mkdir  (PHP  3,  PHP  4  >=  4.0.0) 


Crea  un  directorio 


int  mkdir  (string  pathname,  int  mode) 


Trata  de  crear  el  directorio  especificado  por  pathname. 

Ten  en  cuenta  que  debes  especifiar  el  modo  como  un  numero  octal,  lo  que  significa  que  debes 
anteponerle  un  0  al  numero. 

mkdir  ("/path/to/my/dir",  0700); 


Devuelve  true  en  caso  de  exito  y  false  en  caso  de  fallo. 
Ver  tambien  rmdir'). 


pclose  (PHP  3,  PHP  4  >=4.0.0) 

Cierra  el  fichero  de  proceso  apuntado 

int  pclose  (int  fp) 


Cierra  un  fichero  que  representa  un  tuberia  (pipe)  abierta  con  popcn '). 

El  apuntador  al  fichero  debe  ser  valido,  y  debe  haber  sido  devuelto  por  una  llamada  con  exito  a  popcn '). 
Devuelve  el  estado  de  termination  del  proceso  que  estaba  ejecutandose. 

Ver  tambien  popen'). 
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popen  (PHP  3,  PHP  4  >=  4.0.0) 

Abre  el  fichero  de  proceso  apuntado 

int  popen  (string  command,  string  mode) 


Abre  una  tuberfa  (pipe)  a  un  proceso  ejecutado  haciendo  fork  al  comando  dado  por  command 

Devuelve  un  apuntador  de  fichero  identico  al  devuelto  por  fopcn '),  excepto  que  este  es  unidireccional 
(solo  puede  usarse  o  para  leer  o  para  escribir)  y  debe  cerrarse  con  pclose ').  Este  apuntador  puede  usarse 
con  fgets(),  fgetss'),  y  fputs(). 

Si  ocurre  un  error,  devuelve  false. 

$fp  =  popen  ("/bin/ls",  "r"); 


Ver  tambien  pclose '). 


readfile  (PHP  3,  PHP  4  >=  4.0.0) 

Muestra  el  contenido  de  un  fichero 


int  readfile  (string  filename,  int  [use_include_path] ) 


Lee  un  fichero  y  lo  escribe  a  la  salida  estandar. 

Devuelve  el  numero  de  bytes  leidos  del  fichero.  Si  ocurre  un  error,  se  devuelve  false  y  a  menos  que  la 
funcion  fuera  llamada  como  @readfile,  se  imprime  un  mensaje  de  error 

Si  filename  comienzo  por  "http://"  (no  es  sensible  a  mayusculas),  se  abre  una  conexion  HTTP  1.0  al 
servidor  especificado  y  el  texto  de  la  respuesta  se  escribe  a  la  salida  estandar. 

No  maneja  redirecciones  HTTP,  por  eso  se  debe  incluir  una  barra  final  cuando  se  trata  de  directorios. 

Si  filename  comienza  con  "ftp://"  (no  es  sensible  a  mayusculas),  se  abre  una  conexion  ftp  al  servidor 
especificado  y  el  fichero  que  se  pide  se  escribe  en  la  salida  estandar.  Si  el  servidor  no  soporta  ftp  en 
modo  pasivo,  la  funcion  fallara. 

Si  filename  no  comienza  con  ninguna  de  las  cadenas  anteriores,  el  fichero  sera  abierto  del  sistema  de 
ficheros  y  su  contenido  escrito  en  la  salida  estandar. 

Se  puede  usar  el  segundo  parametro  opcional  y  fijarlo  a  "1",  si  si  quieres  que  tambien  se  busque  el 
fichero  en  el  include_path 

Ver  tambien  fpassthnL),  file  '),  fopcn  ),  include^),  require  ),  y  virtual  ). 
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readlink  (PHP  3,  PHP  4  >=  4.0.0) 

Devuelve  el  objetivo  de  un  enlace  simbolico 

string  readlink  (string  path) 

readlink()  hace  lo  mismo  que  la  funcion  C  readlink  C  y  devuelve  el  contenido  del  path  del  enlace 
simbolico  o  0  en  caso  de  error. 

Ver  tambien  symlink '),  readlinkO  y  linkinfo  ). 


rename  (PHP  3,  PHP  4  >=  4.0.0) 

Renombra  un  fichero 

int  rename  (string  oldname ,  string  newname ) 

Trata  de  renombrar  oldname  como  newname. 

Devuelve  true  en  caso  de  exito  y  false  en  caso  de  fallo. 


rewind  (PHP  3,  PHP  4  >=  4.0.0) 

Rebobina  la  posicion  del  apuntador  al  fichero 

int  rewind  (int  fp) 


Fija  el  indicador  de  posicion  del  fichero  dado  por  fp  al  comienzo  de  del  fichero. 

Si  ocurre  un  error,  devuelve  0. 

El  apuntador  al  fichero  debe  ser  valido,  y  debe  apuntar  a  un  fichero  abierto  con  exito  por  fopen  '). 
Ver  tambien  fseek  )  y  ftell '). 


rmdir  (PHP  3,  PHP  4  >=  4.0.0) 


Elimina  un  directorio 
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int  rmdir  (string  dirname ) 


Trata  de  eliminar  el  directorio  indicado  por  pathname.  El  directorio  debe  estar  vacio,  y  los  permisos 
relevantes  deben  permitir  esto. 

Si  ocurre  un  error,  devuelve  0. 

Ver  tambien  mkdir  ). 


stat  (PHP  3,  PHP  4  >=  4.0.0) 

Da  information  sobre  un  fichero 


array  stat  (string  filename) 


Recoje  los  datos  sobre  el  fichero  indicado  por  filename. 

Devuelve  un  array  conteniendo  los  datos  del  fichero  con  los  siguientes  elementos: 

1 .  dispositivo  (device) 

2.  inode 

3.  modo  de  protection  del  inode 

4.  numero  de  enlaces 

5.  id  de  usuario  del  propietario 

6.  id  de  grupo  del  propietario 

7.  tipo  de  dispositivo  si  es  un  inode  device  * 

8.  tamano  en  bytes 

9.  fecha  del  ultimo  acceso  access 

10.  fecha  de  la  ultima  modification 

1 1 .  fecha  del  ultimo  cambio 

12.  tamano  del  bloque  para  el  sistema  I/O  * 

13.  numero  de  bloques  ocupados 

*  -  solo  valido  en  sistemas  que  soportan  el  tipo  st_blksize  —  otros  sistemas  (como  Windows)  devuelven  -1 
Los  resultados  de  esta  funcion  son  cacheados.  Ver  clearstatcache ')  para  mas  detalles. 
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Istat  (PHP  3>=  3.0.4,  PHP  4  >=  4.0.0) 

Da  information  sobre  un  fichero  o  enlace  simbolico 


array  Istat  (string  filename) 


Refine  los  datos  del  fichero  o  enlace  simbolico  indicado  por  filename.  Esta  funcion  es  identica  a  la 
funcion  stat ')  excepto  que  si  el  nombre  en  el  parametro  filename  es  un  enlace  simbolico,  son 
devueltos  los  datos  (status)  del  enlace  simbolico,  y  no  los  del  fichero  al  que  apunta  el  enlace  simbolico. 

Devuelve  un  array  conteniendo  los  datos  del  fichero  con  los  siguientes  elementos: 

1 .  dispositivo  (device) 

2.  inode 

3.  nfimero  de  enlaces 

4.  id  de  usuario  del  propietario 

5.  id  de  grupo  del  propietario 

6.  tipo  de  disposivo  si  es  un  inode  device  * 

7.  tamano  en  bytes 

8.  fecha  del  ultimo  acceso 

9.  fecha  de  la  ultima  modification 

10.  fecha  del  ultimo  cambio 

1 1 .  tamano  de  bloque  para  el  sistema  I/O  * 

12.  numero  de  bloques  ocupados 

*  -  solo  valido  en  sistemas  que  soportan  el  tipo  st_blksize  —  otros  sistemas  (como  Windows)  devuelven  -1 
Los  resultados  de  esta  funcion  son  cacheados.  Ver  clearstatcache  )  para  mas  detalles. 


symlink  (PHP  3,  PHP  4  >=  4.0.0) 

Crea  un  enlace  simbolico 

int  symlink  (string  target,  string  link) 

symlink()  crea  un  enlace  simbolico  del  objetivo  target  con  el  nombre  especificado  por  link. 
Ver  tambien  link/)  para  crear  enlaces  fuertes,  y  readlink  )  junto  con  linkinfo  ). 
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tempnam  (PHP  3,  PHP  4  >=  4.0.0) 

Crea  un  fichero  de  nombre  unico 


string  tempnam  (string  dir,  string  prefix) 


Crea  un  fichero  temporal  de  nombre  unico  en  el  directorio  especificado.  Si  el  directorio  no  existe 
tempnam()  puede  generar  un  fichero  en  el  directorio  temporal  del  sistema. 

El  comportamiento  de  la  funcion  tempnam()  depende  del  sistema.  En  Windows  la  variable  de  entorno 
TMP  se  impone  sobre  el  parametro  dir,  en  Linux  la  variable  de  entorno  TMPDIR  tiene  preferencia, 
mientras  que  en  SVR4  siempre  se  usara  el  parametro  dir  si  si  el  directorio  al  que  apunta  existe. 
Consulta  la  documentation  del  sistema  sobre  la  funcion  tempnam(3)  en  caso  de  duda. 

Devuelve  el  nombre  del  nuevo  fichero  temporal,  o  una  cadena  nula  en  caso  de  fallo. 

Ejemplo  1.  Ejemplo  de  tempnam() 

$tmpfname  =  tempnam  ("/tmp",  "FOO"); 


touch  (PHP  3,  PHP  4  >=  4.0.0) 

Fija  la  fecha  de  modification  de  un  fichero 

int  touch  (string  filename,  int  time) 

Trata  de  fijar  la  fecha  de  modification  del  fichero  indicado  por  filename  al  valor  dado  por  time.  Si  no  se 
pone  la  option  time,  se  utiliza  la  fecha  actual. 

Si  el  fichero  no  existe,  sera  creado. 

Devuelve  true  en  caso  de  exito  y  false  en  otro  caso. 

umask  (PHP  3,  PHP  4  >=  4.0.0) 

Cambia  la  umask  actual 

int  umask  (int  mask) 
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umask()  fija  las  umask  PHP  con  la  mascara  &  0777  y  y  devuelve  la  antigua  umask.  Cuando  PHP  se  esta 
usando  como  un  modulo  del  servidor,  la  umask  se  restaura  cuando  cada  peticion  es  finalizada. 

umask()  sin  argumentos  solamente  devuelve  la  umask  actual. 


unlink  (PHP  3,  PHP  4  >=  4.0.0) 
Borra  un  fichero 


int  unlink  (string  filename) 


Borra  el  fichero  filename.  Es  similar  a  la  funcion  unlink!)  del  Unix  C. 
Devuelve  0  o  false  en  caso  de  error. 

Ver  tambien  rmdir  )  para  borrar  directorios. 
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XXVII.  Funciones  Forms  Data  Format  (Formato 
de  Datos  de  Formularios) 

El  Formato  de  Datos  de  Formulario  (FDF)  esta  disenado  para  el  manejo  de  formularios  en  archivos  PDF. 
Se  aconseja  leer  la  informacion  disponible  en 

http://partners.adobe.com/asn/developer/acrosdk/forms.html  para  mas  informacion  sobre  lo  que  es  FDF 
y  como  se  usa  en  general. 

Nota:  Actualmente  Adobe  solo  proporciona  una  version  compatible  con  Iibc5  para  Linux.  Las 
pruebas  con  glibc2  provocaron  un  fallo  de  segmentado.  Si  alguien  es  capaz  de  hacerla  funcionar, 
por  favor  comentelo  en  esta  pagina. 


Nota:  Si  tiene  problemas  configurando  php  con  soporte  de  fdftk,  compruebe  si  el  archivo  de 
cabecera  FdfTk.h  y  la  librena  libFdfTk.so  estan  en  su  lugar  correcto.  Deberfan  encontrarse 
respectivamente  en  fdftk-dir/include  y  en  fdftk-dir/lib.  Este  problema  no  se  dara  si  se  limita  a 
desempaqueta  la  distribucon  del  FtdTk. 


Fa  idea  general  del  FDF  es  similar  a  los  formularios  HTMF.  Fa  diferencia  basicamente  esta  en  el 
formato  en  que  se  transmiten  los  datos  al  servidor  cuando  se  pulsa  el  boton  de  envfo  (este  es  realmente  el 
Formato  de  Datos  de  Formulario)  y  el  formato  del  formulario  en  si  mismo  (que  es  el  Formato  de 
Documento  Portable,  PDF).  Procesar  lo  datos  del  FDF  es  una  de  las  caracterfsticas  que  proporcionan  las 
funciones  fdf.  Pero  aun  hay  mas.  Uno  tambien  puede  tomar  un  formulario  PDF  y  rellenar  los  campos  de 
entrada  con  datos  sin  modificar  el  formulario  en  si  mismo.  En  dicho  caso,  lo  que  se  hace  es  crear  un 
documento  FDF  (fdf_create')),  fijar  los  valores  de  cada  campo  de  entrada  (fdf_set_value())  y  asociarlo 
con  un  formulario  PDF  (fdf_set_file')).  Finalmente,  debe  ser  enviado  al  navegador  con  el  Mime  Type 
application/vnd.fdf.  El  plug-in  de  Acrobar  reader  de  su  navegador  reconoce  el  Mime  Type,  lee  el 
formulario  PDF  asociado  y  rellena  los  datos  a  partir  del  documento  FDF. 

Fos  siguientes  ejemplos  muestran  como  se  evaluan  los  datos  de  los  formularios. 


Ejemplo  1.  Evaluando  un  documento  FDF 

<?php 

/ /  Guarda  los  datos  FDF  en  un  archivo  temporal 
$fdffp  =  f open ( "test . fdf " ,  "w "); 

fwrite ($fdffp,  $HTTP_FDF_DATA,  strlen ( $HTTP_FDF_DATA) ) ; 
fclose ($fdffp) ; 

/ /  Abre  archivo  temporal  y  evalua  los  datos 

//El  formulario  pdf  contenia  varios  campos  de  texto  con  los  nombres 

//  volumen,  fecha,  comentario,  editorial,  preparador,  y  dos  casillas  de  verificacion 
//  muestra_editorial  y  muestra_preparador . 

$fdf  =  fdf_open ( "test . fdf ")  ; 

$volume  =  f df_get_value ( $fdf ,  "volumen"); 

echo  "El  campo  volumen  tiene  el  valor  ' <B>$volume</B>' <BR>" ; 
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$date  =  fdf_get_value ($fdf ,  "fecha"); 

echo  "El  campo  fecha  tiene  el  valor  ' <B>$date</B>' <BR>" ; 

$comment  =  fdf_get_value ( $f df ,  " comentario" ) ; 

echo  "El  campo  comentario  tiene  el  valor  ' <B>$comment</B>' <BR>" ; 

if ( f df_get_value ($fdf ,  "muestra_editorial " )  ==  "On")  { 

$publisher  =  f df_get_value ($fdf ,  "editorial"); 

echo  "El  campo  editorial  tiene  el  valor  ' <B>$publisher</B>' <BR>" ; 
}  else 

echo  "No  se  debe  mostrar  la  editorial . <BR> " ; 

if ( f df_get_value ($fdf ,  "muestra_preparador " )  ==  "On")  { 

$preparer  =  fdf_get_value ($fdf ,  "preparador"); 

echo  "El  campo  preparador  tiene  el  valor  ' <B>$preparer</B>' <BR>" ; 
}  else 

echo  "No  se  debe  mostrar  el  preparador . <BR>" ; 
fdf_close ($fdf ) ; 

?> 
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fdf_open  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 
Abrir  un  documento  FDF 


int  fdf_open  (string  filename) 


La  funcion  fdf_open()  abre  un  archivo  con  datos  de  formulario.  Este  archivo  debe  contener  los  datos  tal 
y  como  se  devuelven  en  un  formulario  PDF.  Actualmente  dicho  archivo  debe  crearse  "manualmente" 
usando  la  funcion  I'opcn ')  y  escribiendo  en  este  el  contenido  de  HTTP_FDF_DATA  usando  fwrite').  No 
existe  un  mecanismo  similar  al  de  los  formularios  HTML  donde  se  crea  una  variable  para  cada  campo  de 
entrada. 


Ejemplo  1.  Accediendo  a  los  datos  del  formulario 

<?php 

/ /  Guarda  los  datos  FDF  en  un  archivo  temporal 
$fdffp  =  fopen ( "test . fdf " ,  "w"); 

fwrite ($fdffp,  $HTTP_FDF_DATA,  strlen ( $HTTP_FDF_DATA) ) ; 
fclose ($fdffp) ; 

/ /  Abre  archivo  temporal  y  evalua  los  datos 
$fdf  =  fdf_open ( "test . fdf ") ; 

fdf_close ($fdf ) ; 

?> 


Vea  tambien  fdf_close '). 

fdf_close  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 

Cerrar  un  documento  FDF 

void  fdf_close  (int  fdf_document) 

La  funcion  fdf_close()  cierra  un  documento  FDF. 
Vea  tambien  fdf_open(). 
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fdf_create  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 


Crear  un  documento  FDF 


int  fdf_create  (void  ) 


La  funcion  fdf_create()  crea  un  documento  FDF  nuevo.  Esta  funcion  se  necesita  si  se  desea  rellenar  los 
campos  de  entrada  en  un  documento  PDF. 


Ejemplo  1.  Rellenando  un  documento  PDF 

<?php 

$outfdf  =  f df_create ( )  ; 

f df_set_value ( $outf df ,  "volumen",  $volume,  0); 

f df_set_f ile ( $out fdf ,  "http : /testf df / result label . pdf" ) ; 
fdf_save ( $outf df ,  "outtest . fdf" )  ; 
fdf_close ($outfdf )  ; 

Header ( "Content -type :  applicat ion/vnd . f df " ) ; 

$fp  =  fopen ("outtest . fdf ",  "r"); 
fpassthru ($fp) ; 
unlink ( "outtest . fdf" ) ; 

?> 


Vea  tambien  fdf_close '),  fdf_save(),  fdf_open(). 


fdf  save 


(PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 


Guardar  un  documeto  FDF 


int  fdf_save  (string  filename) 


La  funcion  fdf_save()  guarda  un  documento  FDF.  El  kit  de  FDF  proporciona  una  forma  de  volcar  el 
documento  a  stdout  si  el  parametro  filename  es  Esto  no  funciona  si  el  PHP  se  utiliza  como  un 
modulo  del  apache.  En  tal  caso  se  debera  escribir  a  un  fichero  y  utilizar  p.  ej.  fpassthru')  para 
visualizarlo. 

Vea  tambien  fdf_close ')  y  el  ejemplo  para  fdf_create'j. 
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fdf_get_value  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 

Obtener  el  valor  de  un  campo 

string  fdf_get_value  (int  fdf_document ,  string  fieldname) 

La  funcion  fdf_get_value()  devuelve  el  valor  de  un  campo. 

Vea  tambien  fdf_set_value  ')- 


fdf  set_value  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 


Fijar  el  valor  de  un  campo 


void  fdf_set_value  (int  fdf_document ,  string  fieldname,  string  value,  int 
isName) 


La  funcion  fdf_set_value()  fija  el  valor  de  un  campo.  El  parametro  final  determina  si  el  valor  del  campo 
se  debera  convertir  a  un  Nombre  PDF  ( IsName  =  1)  o  convertir  en  una  Cadena  PDF  ( isName  =  0). 

Vea  tambien  fdf_get_value '). 


fdf  next_f ield_name  (php  3>=  3.0.6,  php  4  >=  4.0.0 


Obtener  el  nombre  del  siguiente  campo 


string  fdf_next_f ield_name  (int  fdf_document ,  string  fieldname) 

La  funcion  fdf_next_field_name()  devuelve  el  nombre  del  campo  tras  el  campo  fieldname  o  el 
nombre  del  primer  campo  si  el  segundo  parametro  es  null. 

Vea  tambien  fdf_set_field(),  fdf_get_field(). 


fdf_set_ap  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 


Ajusta  la  apariencia  de  un  campo 
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void  fdf_set_ap  (int  fdf_document ,  string  field_name,  int  face,  string 
filename,  int  page_number) 


La  funcion  fdf_set_ap()  ajusta  la  apariencia  de  un  campo  (p.  ej.  el  valor  de  la  clave  /AP).  Los  valores 
posibles  de  face  son  l=FDFNormalAP,  2=FDFRolloverAP,  3=FDFDownAP 


fdf_set_status  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 

Fija  el  valor  de  la  clave  /STATUS 

void  fdf_set_status  (int  fdf_document ,  string  status) 

La  funcion  fdf_set_status()  fija  el  valor  de  la  clave  /STATUS. 

Vea  tambien  fdf_get_status '). 

fdf_get_status  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 

Obtener  el  valor  de  la  clave  /STATUS 

string  fdf_get_status  (int  fdf_document) 

La  funcion  fdf_get_status()  devuelve  el  valor  de  la  clave  /STATUS. 

Vea  tambien  fdf_set_status(). 

fdf_set_file  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 

Fijar  el  valor  de  la  clave  IF 

void  fdf_set_file  (int  fdf_document ,  string  filename) 

La  funcion  fdf_set_file()  fija  el  valor  de  la  clave  /F.  La  clave  /F  es  simplemente  una  referenda  a  un 
formulario  PDF  que  se  va  a  rellenar  con  datos.  En  un  entorno  web  es  un  URL  (p.ej. 
http:/testfdf/resultlabel.pdf). 

Vea  tambien  fdf_get_fileO  y  el  ejemplo  para  fdf_create )). 
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fdf_get_file  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 

Obtener  el  valor  de  la  clave  /F 

string  fdf_get_file  (int  fdf_document ) 

La  funcion  fdfset_fi  I e ))  devuelve  el  valor  de  la  clave  /F. 
Vea  tambien  fdf_set_file'). 
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XXVIII.  Funciones  FTP 


FTP  es  el  acronimo  de  File  Transfer  Protocol  (Protocolo  de  Transference  de  Ficheros. 

Cuando  se  utiliza  el  modulo  FTP,  se  definen  las  siguientes  constantes:  FTP_ASCII,  y  FTP_BINARY. 
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FTP 


Establece  una  conexion  FTP 

int  ftp_connect  (string  host,  int  [port]) 

Si  tiene  exito,  devuelve  un  flujo  FTP.  En  caso  de  error,  devuelve  false. 

ftp_connect()  establece  una  conexion  FTP  al  host  especificado.  El  parametro  port  especifica  un 
puerto  alternativo  al  que  conectar.  Si  se  omite  o  es  cero,  se  usa  el  puerto  FTP  por  defecto,  21. 

ftpjogin  (PHP  3>=  3.0.13,  PHP  4  >=  4.0.0) 

Comienza  la  sesion  en  una  conexion  FTP 

int  ftp_login  (int  ftp_stream,  string  username,  string  password) 

Si  tiene  exito,  devuelve  true.  En  caso  de  error,  devuelve  false. 

Inicia  una  sesion  (envfa  identificador  de  usuario  y  contrasena)  en  el  flujo  FTP  especificado. 

ftp_pwd  (PHP  3>=  3.0.13,  PHP  4  >=  4.0.0) 

Devuelve  el  nombre  del  directorio  actual 

int  ftp_pwd  (int  ftp_stream) 

Devuelve  el  directorio  actual,  o  false  en  caso  de  error. 

ftp_cdup  (PHP  3>=  3.0.13,  PHP  4  >=  4.0.0) 

Cambia  al  directorio  padre 

int  ftp_cdup  (int  ftp_stream) 
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Si  tiene  exito,  devuelve  true.  En  caso  de  error,  devuelve  false. 

Cambia  al  directorio  padre. 

ftp_chdir  (PHP  3>=  3.0.13,  PHP  4  >=  4.0.0) 

Cambia  de  directorio  en  un  servidor  FTP 

int  ftp_chdir  (int  ftp_stream,  string  directory) 

Si  tiene  exito,  devuelve  true.  En  caso  de  error,  devuelve  false. 

Cambia  al  directorio  especificado  por  el  parametro  directory. 

ftp_mkdir  (PHP  3>=  3.0.13,  PHP  4  >=  4.0.0) 

Crea  un  directorio 

string  ftp_mkdir  (int  ftp_stream,  string  directory) 

Si  tiene  exito,  devuelve  el  nombre  del  directorio  recien  creado.  En  caso  de  error,  devuelve  false. 

Crea  el  directorio  especificado  por  el  parametro  directory. 

ftp_rmdir  (PHP  3>=  3.0.13,  PHP  4  >=  4.0.0) 

Borra  un  directorio 

int  ftp_rmdir  (int  ftp_stream,  string  directory) 

Si  tiene  exito,  devuelve  true.  En  caso  de  error,  devuelve  false. 

Borra  el  directorio  especificado  por  el  parametro  directory. 
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FTP 


Devuelve  una  lista  de  ficheros  del  directorio  dado. 

int  ftp_nlist  (int  ftp_stream,  string  directory) 


Si  tiene  exito,  devuelve  un  array  de  nombres  de  fichero.  En  caso  de  error,  devuelve  false. 


ftp_rawlist  (PHP  3>=  3.0.13,  PHP  4  >=  4.0.0) 

Devuelve  una  lista  detallada  de  ficheros  del  directorio  dado. 

int  ftp_rawlist  (int  ftp_stream,  string  directory) 


ftp_rawlist()  ejecuta  el  comando  FTP  LIST,  y  devuelve  el  resultado  como  un  array.  Cada  elemento  del 
array  corresponde  a  una  Knea  de  texto.  La  salida  no  se  procesa  de  ninguna  forma.  Se  puede  utilizar  el 
identificador  de  tipo  de  sistema  devuelto  por  t'tp_sy sty pe ')  para  determinar  como  se  deben  interpretar  los 
resultados. 


ftp_systype  (PHP  3>=  3.0.13,  PHP  4  >=  4.0.0) 

Devuelve  el  identificador  de  tipo  de  sistema  del  servidor  FTP  remoto. 

int  ftp_systype  (int  ftp_stream) 


Devuelve  el  tipo  de  sistema  remoto,  o  false  en  caso  de  error. 


ftp_pasv  (PHP  3>=  3.0.13,  PHP  4  >=  4.0.0) 

Activa  o  desactiva  el  modo  pasivo. 

int  ftp_pasv  (int  ftp_stream,  int  pasv) 


Si  tiene  exito,  devuelve  true.  En  caso  de  error,  devuelve  false. 
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ftp_pasv()  activa  el  modo  pasivo  si  el  parametro  pasv  es  true  (desactiva  el  modo  pasivo  si  pasv  es 
false.)  En  modo  pasivo,  las  conexiones  de  datos  son  iniciadas  por  el  cliente,  en  lugar  de  ser  iniciadas 
por  el  servidor. 

ftp_get  (PHP  3>=  3.0.13,  PHP  4  >=  4.0.0) 

Descarga  un  fichero  del  servidor  FTP. 

int  ftp_get  (int  ftp_stream,  string  local_file,  string  remote_file,  int  mode) 

Si  tiene  exito,  devuelve  true.  En  caso  de  error,  devuelve  false. 

ftp_get()  baja  el  fichero  remote_file  del  servidor  FTP,  y  lo  guarda  localmente  como  local_file. 
El  modo  de  transference  especificado  por  el  parametro  mode  debe  ser  FTP_ASCII  o  bien 

ftp_binary. 

ftp_fget  (PHP  3>=  3.0.13,  PHP  4  >=  4.0.0) 

Descarga  un  fichero  del  servidor  FTP  y  lo  guarda  en  un  fichero  abierto. 

int  ftp_fget  (int  ftp_stream,  int  fp,  string  remote_file ,  int  mode) 

Si  tiene  exito,  devuelve  true.  En  caso  de  error,  devuelve  false. 

ftp_fget()  baja  el  fichero  remote_file  del  servidor  FTP,  y  lo  escribe  en  el  puntero  a  fichero  fp.  El 
modo  de  transferencia  especificado  por  el  parametro  mode  debe  ser  FTP_ASCII  o  bien  FTP_B INARY. 

ftp_put  (PHP  3>=  3.0.13,  PHP  4  >=  4.0.0) 

Sube  un  fichero  al  servidor  FTP. 

int  ftp_put  (int  ftp_stream,  string  remote_file,  string  local_file,  int  mode) 

Si  tiene  exito,  devuelve  true.  En  caso  de  error,  devuelve  false. 

ftp_put()  sube  el  fichero  local  local_file  al  servidor  FTP  y  lo  guarda  como  remote_file.  El 
modo  de  transferencia  especificado  por  el  parametro  mode  debe  ser  FTP_ASCII  o  bien  FTP_B INARY. 
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FTP 


Sube  un  fichero  abierto  al  servidor  FTP. 

int  ftp_fput  (int  ftp_stream,  string  remote_file,  int  fp,  int  mode) 

Si  tiene  exito,  devuelve  true.  En  caso  de  error,  devuelve  false 

ftp_fput()  sube  los  datos  apuntados  por  el  puntero  a  fichero  fp  hasta  alcanzar  el  final  del  fichero.  Los 
resultados  se  guardan  en  el  fichero  remote_file  del  FTP  remoto.  El  modo  de  transferencia 
especificado  por  el  parametro  mode  debe  ser  FTP_ASCII  o  bien  FTP_BINARY. 

ftp_size  (PHP  3>=  3.0.13,  PHP  4  >=  4.0.0) 

Devuelve  el  tamano  del  fichero  especificado. 

int  ftp_size  (int  ftp_stream,  string  remote_file) 

Si  tiene  exito  devuelve  el  tamano  del  fichero,  o  -1  en  caso  de  error. 

ftp_size()  devuelve  el  tamano  de  un  fichero.  Si  ocurre  algun  error,  o  si  el  fichero  no  existe,  devuelve  -1. 
No  todos  los  servidores  soportan  esta  caracterfstica. 


ftpmdtm  (PHP  3>=  3.0.13,  PHP  4  >=  4.0.0) 

Devuelve  la  fecha  de  ultima  modificacion  del  fichero  especificado. 

int  ftp_mdtm  (int  ftp_stream,  string  remote_file) 


Si  tiene  exito,  devuelve  una  marca  de  tiempo  UNIX  (UNIX  timestamp).  En  caso  de  error,  devuelve  -1. 

ftp_mdtm()  comprueba  la  fecha  de  ultima  modificacion  de  un  fichero,  y  la  devuelve  como  una  marca  de 
tiempo  UNIX.  Si  se  produce  algun  error,  o  el  fichero  no  existe,  devuelve  -1.  Tenga  en  cuenta  que  no 
todos  los  servidores  soportan  esta  caracterfstica. 
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FTP 


Renombra  un  fichero  del  servidor  FTP. 

int  ftp_rename  (int  ftp_stream,  string  from,  string  to) 

Si  tiene  exito,  devuelve  true.  En  caso  de  error,  devuelve  false. 

ftp_rename()  renombra  el  fichero  especificado  por  el  parametro  from  con  el  nuevo  nombre  to 

ftp_delete  (PHP  3>=  3.0.13,  PHP  4  >=  4.0.0) 

Borra  un  fichero  del  servidor  FTP. 

int  ftp_delete  (int  ftp_stream,  string  path ) 

Si  tiene  exito,  devuelve  true.  En  caso  de  error,  devuelve  false. 

ftp_delete()  borra  el  fichero  especificado  por  el  parametro  path  del  servidor  FTP. 

ftp_quit  (PHP  3>=  3.0.13,  PHP  4  >=  4.0.0) 

Cierra  una  conexion  FTP 

int  ftp_quit  (int  ftp_stream) 

ftp_connect I)  cierra  el  flujo  FTP  ftp_stream. 
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These  functions  all  handle  various  operations  involved  in  working  with  functions. 
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call  user  func  (PHP  3>=  3.0.3,  PHP  4  >=  4.0.0) 


Call  a  user  function  given  by  the  first  parameter 

mixed  call_user_func  (string  function_name  [,  mixed  parameter  [,  mixed 


Call  a  user  defined  function  given  by  the  function_name  parameter.  Take  the  following: 

function  barber  ($type)  { 

print  "You  wanted  a  $type  haircut,  no  problem"; 

} 

call_user_func  ('barber',  "mushroom") ; 
call_user_func  ('barber',  "shave"); 


create_f  unction  {php  4  > 

Create  an  anonymous  (lambda-style)  function 

string  create_function  (string  args,  string  code) 


Creates  an  anonymous  function  from  the  parameters  passed,  and  returns  a  unique  name  for  it.  Usually 
the  args  will  be  passed  as  a  single  quote  delimited  string,  and  this  is  also  recommended  for  the  code. 
The  reason  for  using  single  quoted  strings,  is  to  protect  the  variable  names  from  parsing,  otherwise,  if 
you  use  double  quotes  there  will  be  a  need  to  escape  the  variable  names,  e.g.  \$avar. 

You  can  use  this  function,  to  (for  example)  create  a  function  from  information  gathered  at  run  time: 

Ejemplo  1.  Creating  an  anonymous  function  with  create_function() 

$newfunc  =  create_function (' $a, $b' ,' return  "ln($a)  +  ln($b)  =  ",log($a  *  $b) ; ' ) 
echo  "New  anonymous  function:  $newfunc\n"; 
echo  $newfunc (2, M_E) . "\n" ; 

/ /  outputs 

//  New  anonymous  function:  lambda_l 

//  in  (2)  +  in  (2 . 718281828459)  =  1.6931471805599 

Or,  perhaps  to  have  general  handler  function  that  can  apply  a  set  of  operations  to  a  list  of  parameters: 
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Ejemplo  2.  Making  a  general  processing  function  with  create_function() 

function  process ($varl,  $var2,  $farr)  { 
for  ( $ f =0 ;  $f  <  count  ($farr) ;  $f++) 
echo  $farr[$f] ( $var 1 , $var2 ) . "\n"; 

} 


/ /  create  a  bunch  of  math  functions 

$fl  =  'if  ($a  >=0)  {return  "b*aA2  =  " . $b*sqrt ( $a) ; }  else  {return  false;}'; 

$f2  =  "return  \"min(bA2+a,  aA2,b)  =  \ " . min ( \$a*\$a+\$b, \$b*\$b+\$a) ; " ; 

$f3  =  'if  ($a  >  0  &&  $b  !=  0)  {return  "ln(a)/b  =  " . log ( $  a ) /$b; }  else  {return  false;} 
$farr  =  array ( 

'return  "some  trig:  " .  (sin  ($x)  +  $x*cos  ( $y ) ) ; ' ) , 

'return  "a  hypotenuse:  ".sqrt($x*$x  +  $y*$y) ; ' ) , 

$fl)  , 

$f2)  , 

$f  3) 


create_f unction (' $x, $y' , 
create_f unction (' $x, $y' , 
create_f unction (' $a, $b' , 
create_f unction (' $a, $b' , 
create_f unction (' $a, $b' , 
)  ; 


echo  "\nUsing  the  first  array  of  anonymous  functions\n" ; 
echo  "parameters:  2.3445,  M_PI\n"; 
process  (2 . 3445,  M_PI,  $farr) ; 

//  now  make  a  bunch  of  string  processing  functions 
$garr  =  array ( 

create_f unction ( ' $b, $a' , ' if  ( strncmp ( $a, $b, 3 )  ==  0)  return  "**  \"$a\"  '. 

'and  \"$b\"\n**  Look  the  same  to  me!  (looking  at  the  first  3  chars)";'), 
create_f unction (' $a, $b' ,' ;  return  "CRCs:  " . crc32 ($a)  . "  ,  " . crc32  (b) ; ' ) , 

create_f unction ( ' $a, $b' , ' ;  return  " similar (a, b)  =  " . similar_text ($a, $b, &$p) . " ($p 
)  ; 

echo  "\nUsing  the  second  array  of  anonymous  functions\n" ; 

process ("Twas  brilling  and  the  slithy  toves",  "Twas  the  night",  $garr) ; 

and  when  you  run  the  code  above,  the  output  will  be: 


Using  the  first  array  of  anonymous  functions 

parameters:  2.3445,  M_PI 

some  trig:  -1.6291725057799 

a  hypotenuse:  3.9199852871011 

b*aA2  =  4.8103313314525 

min  (bA2+a,  aA2,b)  =  8.6382729035898 

In  (a/b)  =  0.27122299212594 

Using  the  second  array  of  anonymous  functions 

**  "Twas  the  night"  and  "Twas  brilling  and  the  slithy  toves 

**  Look  the  same  to  me!  (looking  at  the  first  3  chars) 

CRCs:  -725381282  ,  1908338681 
similar (a, b)  =  11(45.833333333333%) 
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But  perhaps  the  most  common  use  for  of  lambda-style  (anonymous)  functions  is  to  create  callback 
functions,  for  example  when  using  array _walk')  or  usort) 

Ejemplo  3.  Using  anonymous  functions  as  callback  functions 

$av  =  array ("the  ","a  ","that  ","this  "); 

array_walk ( $av,  create_function ( ' & $v, $k' , ' $v  =  $v . "mango" ;')) ; 
print_r ( $av) ;  //  for  PHP3  use  var_dump ( ) 

/ /  outputs : 

/ /  Array 

//  ( 

//  [0]  =>  the  mango 

/  /  [ 1 ]  =>  a  mango 

//  [2]  =>  that  mango 

//  [3]  =>  this  mango 

//  ) 

//  an  array  of  strings  ordered  from  shorter  to  longer 

$sv  =  array (" small larger ", "a  big  string", "it  is  a  string  thing"); 

print_r ( $sv) ; 

/ /  outputs : 

/ /  Array 

//  ( 

//  [0]  =>  small 

//  [1]  =>  larger 

//  [2]  =>  a  big  string 

//  [3]  =>  it  is  a  string  thing 

//  ) 

/ /  sort  it  from  longer  to  shorter 

usort ($sv,  create_function (' $a, $b' ,'  return  strlen($b)  -  strlen ($a) ; ' ) ) ; 
print_r ( $sv) ; 

/ /  outputs : 


II 

Array 

II 

( 

// 

[0] 

=  > 

it  is  a  string  thing 

// 

[1] 

=  > 

a  big  string 

// 

[2] 

=  > 

larger 

// 

[3] 

=  > 

small 

// 

) 

func_get_arg  (php4>=4oo) 

Devuelve  un  elemento  de  la  lista  de  argumentos. 

int  func_get_arg  (int  arg_num) 
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Devuelve  el  argumento  que  esta  en  la  posicion  arg_num  en  la  lista  de  argumentos  de  una  funcion 
definida  por  el  usuario.  Los  argumentos  de  la  funcion  se  cuentan  comenzando  por  la  posicion  cero. 
func_get_arg()  generara  un  aviso  si  se  llama  desde  fuera  de  la  definicion  de  la  funcion. 

Si  arg_num  es  mayor  que  el  numero  de  argumentos  pasados  realmente,  se  generara  un  aviso  y 
func_get_arg()  devolvera  false. 


<?php 

function  f oo  ( )  { 

$numargs  =  func_num_args ( ) ; 

echo  "Number  of  arguments:  $numargs<br>\n" ; 
if  (  $numargs  >=  2  )  { 

echo  "Second  argument  is:  "  .  func_get_arg (  1  )  .  "<br>\n"; 


} 

too  (  1 ,  2 ,  3  ) ; 
?> 


func_get_arg()  puede  utilizarse  conjuntamente  con  func_num_args ')  y  func_get_args')  para  permitir  a 
las  funciones  definidas  por  el  usuario  que  acepten  listas  de  argumentos  de  longitud  variable. 

Nota:  Esta  funcion  fue  anadida  en  PHP  4. 


f  unc_get_args  (php  4  >=  4.o.o) 


Devuelve  un  array  que  contiene  la  lista  de  argumentos  de  una  funcion. 


int  func_get_args  (void  ) 


Devuelve  un  array  en  el  que  cada  elemento  es  el  miembro  correspondiente  de  la  lista  de  argumentos  de  la 
funcion  definida  por  el  usuario  actual.  func_get_args()  generara  un  aviso  si  es  llamada  desde  fuera  de  la 
definicion  de  la  funcion. 


<?php 

function  foo ( )  { 

$numargs  =  func_num_args ( ) ; 

echo  "Number  of  arguments:  $numargs<br>\n" ; 
if  (  $numargs  >=  2  )  { 

echo  "Second  argument  is:  "  .  func_get_arg (  1  )  .  "<br>\n"; 
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} 

$arg_list  =  func_get_args ( ) ; 

for  (  $ i  =  0 ;  $i  <  $numargs;  $i++  )  { 

echo  "Argument  $i  is:  "  .  $arg_list [$i ]  .  "<br>\n"; 

} 


f oo  (  1 ,  2 ,  3  ) ; 
?> 


func_get_args()  puede  utilizarse  conjuntamente  con  fu nc_num_args ')  y  func_get_arg')  para  permitir  a 
las  funciones  definidas  por  el  usuario  que  acepten  listas  de  argumentos  de  longitud  variable. 

Nota:  Esta  funcion  fue  anadida  en  PHP  4. 


f  unc_num_args  <php  4  >=  4.o.0) 


Devuelve  el  numero  de  argumentos  pasados  a  la  funcion. 


int  func_num_args  (void  ) 


Devuelve  el  numero  de  argumentos  pasados  a  la  funcion  actual  definida  por  el  usuario. 
func_num_args()  generara  un  aviso  si  es  llamada  desde  fuera  de  la  definicion  de  la  funcion. 


<?php 

function  foo ( )  { 

$numargs  =  func_num_args ( ) ; 

echo  "Number  of  arguments:  $numargs\n"; 

} 

foo (  1,  2,  3  );  //  Prints  'Number  of  arguments:  3' 

?> 


func_num_args()  puede  utilizarse  conjuntamente  con  func_get_arg')  y  func_get_args')  para  permitir  a 
las  funciones  definidas  por  el  usuario  que  acepten  listas  de  argumentos  de  longitud  variable. 

Nota:  Esta  funcion  fue  anadida  en  PHP  4. 
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functionexists  (PHP  3>=  3.0.7,  PHP  4  >=  4.0.0) 

Devuelve  true  si  la  funcion  dada  ha  sido  definida 

int  function_exists  (string  function_name) 

Consulta  la  lista  de  funciones  definidas  buscando  function_name  (nombre  de  funcion).  Devuelve 
true  si  encuentra  el  nombre  de  funcion  dado,  false  en  otro  caso. 

registershutdownf  unction  (php  3>=  3.0.4,  php  4  >=  4  0  0) 

Registra  una  funcion  para  su  ejecucion  en  el  cierre. 

int  register_shutdown_function  (string  func ) 

Registra  la  funcion  nombrada  en  func  para  que  se  ejecute  cuando  el  script  procese  su  finalizacion. 
Aviso: 

Debido  a  que  no  se  permite  ningun  tipo  de  salida  en  el  navegador  en  esta  funcion,  no  sera  capaz  de 
depurarla  utilizando  sentencias  como  print  o  echo. 
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bindtextdomain  (php  3>=  3.0.7,  PHP  4  >=  4 .0 .0) 

Establece  la  ruta  para  un  dominio 

string  bindtextdomain  (string  domain,  string  directory) 

La  funcion  bindtextdomain()  establece  la  ruta  para  el  dominio. 


dcgettext  (PHP  3>=  3.0.7,  PHP  4  >=  4.0.0) 

Omite  el  dominio  para  una  unica  busqueda 

string  dcgettext  (string  domain,  string  message,  int  category) 

Esta  funcion  permite  omitir  el  dominio  actual  para  una  busqueda  de  un  mensaje.  Ademas  permite 
especificar  una  categorfa. 


dgettext  (PHP  3>=  3.0.7,  PHP  4  >=  4.0.0) 

Omite  el  dominio  actual 

string  dgettext  (string  domain,  string  message) 

La  funcion  dgettext()  permite  omitir  el  dominio  actual  para  una  unica  busqueda. 


gettext  (PHP  3>=  3.0.7,  PHP  4  >=  4.0.0) 

Realiza  una  busqueda  del  mensaje  en  el  dominio  actual 

string  gettext  (string  message) 

Esta  funcion  devuelve  la  traduccion  de  la  cadena  si  encuentra  una  en  la  tabla  de  traducciones,  o  el 
mensaje  enviado  si  no  se  encuentra  ninguna.  Puede  usar  un  caracter  de  subrayado  como  un  alias  para  esta 
funcion. 
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Ejemplo  1.  gettext()-check 

<?php 

/ /  Establece  el  idioma  en  aleman 
putenv  ("LANG=de"); 

//  Especifica  la  localizacion  de  las  tablas  de  traduccion 
bindtextdomain  ("myPHPApp",  "./locale"); 

//  Elige  un  dominio 
textdomain  ("myPHPApp"); 

//  Imprime  un  mensaje  de  prueba 

print  (gettext  ("Welcome  to  My  PHP  Application")); 

?> 


textdomain  (PHP  3>=  3.0.7,  PHP  4  >=  4.0.0) 
Establece  el  dominio  actual 

int  textdomain  ([string  library ]) 


Esta  funcion  establece  el  dominio  en  el  que  se  realizaran  las  busquedas  provocadas  por  las  llamadas  a 
gettext  '),  normalmente  el  nombre  dado  a  la  aplicacion.  Se  devuelve  el  dominio  anterior.  Puede  llamar  a 
la  funcion  sin  parametros  para  obtener  el  dominio  actual  sin  necesidad  de  cambiarlo. 
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These  functions  allow  you  to  work  with  arbitrary-length  integers  using  GNU  MP  library.  In  order  to  have 
these  functions  available,  you  must  compile  PHP  with  GMP  support  by  using  the  — with-gmp  option. 

You  can  download  the  GMP  library  from  http://www.swox.com/gmp/.  This  site  also  has  the  GMP 
manual  available. 

You  will  need  GMP  version  2  or  better  to  use  these  functions.  Some  functions  may  require  more  recent 
version  of  the  GMP  library. 

These  functions  have  been  added  in  PHP  4.0.4. 

Nota:  Most  GMP  functions  accept  GMP  number  arguments,  defined  as  resource  below.  However, 
most  of  these  functions  will  accept  also  numeric  and  string  arguments,  given  it's  possible  to  convert 
the  latter  to  number.  Also,  if  there’s  faster  function  that  can  operate  on  integer  arguments,  it  would  be 
used  instead  of  slower  function  when  supplied  arguments  are  integers.  This  is  done  transparently,  so 
the  bootom  line  is  that  you  can  use  integers  in  every  function  that  expects  GMP  number.  See  also 
gmpjnit')  function. 


Ejemplo  1.  Factorial  function  using  GMP 

<?php 

function  fact  ($x)  { 

if  ($x  <=  1) 
return  1; 

else 

return  gmp_mul  ($x,  fact  ($x-l)); 

} 

print  gmp_strval  (fact  (1000))  .  "\n"; 

?> 


This  will  calculate  factional  of  1000  (pretty  big  number)  very  fast. 
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gmpjnit  (PHP  4  >=  4.0.4) 


Create  GMP  number 


resource  gmp_init  (mixed  number) 


Creates  a  GMP  number  from  integer  or  string.  String  representation  can  be  decimal  or  hexadecimal.  In 
the  latter  case,  the  string  should  start  with  Ox. 


Ejemplo  1.  Creating  GMP  number 

<?php 

$a  =  gmp_init  (123456); 

$b  =  gmp_init  ( " 0xFFFFDEBACDFEDF7200 " ) ; 


Nota:  It  is  not  necessary  to  call  this  function  if  you  want  to  use  integer  or  string  in  place  of  GMP 
number  in  GMP  functions,  like  gmp_add[).  Function  arguments  are  automatically  converted  to  GMP 
numbers,  if  such  conversion  is  possible  and  needed,  using  the  same  rules  as  gmpjnit(). 


gmp_intval(PHP4>=4  0  4) 

Convert  GMP  number  to  integer 

int  gmp_intval  (resource  gmpnumber ) 


This  function  allows  to  convert  GMP  number  to  integer. 


Aviso 

This  function  returns  useful  result  only  if  the  number  actually  fits  the  PHP  integer 
(i.e.,  signed  long  type).  If  you  want  just  to  print  the  GMP  number,  use  gmp_strval  [). 
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gmpstrval  (php  4  >=  4  o  4) 

Convert  GMP  number  to  string 

string  gmp_strval  (resource  gmpnumber  [,  int  base]) 

Convert  GMP  number  to  string  representation  in  base  base.  The  default  base  is  10.  Allowed  values  for 
the  base  are  from  2  to  36. 

Ejemplo  1.  Converting  GMP  number  to  string 

<?php 

$a  =  gmp_init (" 0x41682179 fbf5")  ; 

printf  ("Decimal:  %s,  36-based:  %s",  gmp_strval ( $a) ,  gmp_strval ( $a, 36 ) ) ; 

?> 


gmp_add  (PHP  4  >=  4.0.4) 

Add  numbers 

resource  gmp_add  (resource  a,  resource  b) 

Add  two  GMP  numbers.  The  result  will  be  GMP  number  representing  the  sum  of  the  arguments. 

gmp_sub(PHP4>=4  0  4) 

Subtract  numbers 

resource  gmp_sub  (resource  a,  resource  b) 

Subtract  b  from  a  and  returns  the  result. 
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gmp  _mul(PHP4>=4  0  4) 

Multiply  numbers 

resource  gmp_mul  (resource  a,  resource  b) 


Multiplies  a  by  b  and  returns  the  result. 


g  m  p_d  i  v_q  (php  4  >=  4  o  4) 


Divide  numbers 


resource  gmp_div_q  (resource  a,  resource  b  [,  int  round]) 


Divides  a  by  b  and  returns  the  integer  result.  The  result  rounding  is  defined  by  the  round,  which  can 
have  the  following  values: 

•  GMP_ROUND_ZERO:  The  result  is  truncated  towards  0. 

•  GMP_ROUND_PLUSINF :  The  result  is  rounded  towards  +inf  inity. 

•  GMP_ROUND_MINUSINF:  The  result  is  rounded  towards  -infinity. 

This  function  can  also  be  called  as  gmp_div'). 

See  also  gmp_div_r(),  gmp_div_qr) 


gmp_div_r(PHP4>=4  0  4) 

Remainder  of  the  division  of  numbers 

resource  gmp_div_r  (resource  n,  resource  d  [,  int  round]) 

Calculates  remainder  of  the  integer  division  of  n  by  d.  The  remainder  has  the  sign  of  the  n  argument,  if 
not  zero. 

See  the  gmp_div_q  ')  function  for  description  of  the  round  argument. 

See  also  gmp_div_q '),  gmpdivqr) 
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g  m  p_d  i  v_q  r  (php  4  >=  4  o  4) 

Divide  numbers  and  get  quotient  and  remainder 

array  gmp_div_qr  (resource  n,  resource  d  [,  int  round]) 


The  function  divides  n  by  d  and  returns  array,  with  the  first  element  being  [n/d]  (the  integer  result  of 
the  division)  and  the  second  being  (n  -  [n/d]  *  d)  (the  remainder  of  the  division). 

See  the  gmp_div_q')  function  for  description  of  the  round  argument. 


Ejemplo  1.  Division  of  GMP  numbers 


<?php 

$a  =  gmp_init  ( "0x41682179fbf5" ) ; 

$res  =  gmp_div_qr  ($a,  "0xDEFE75"); 
printf ( "Result  is:  q  -  %s,  r  -  %s", 

gmp_strval  ($res[0]),  gmp_strval 


?> 


($res [1] ) ) ; 


See  also  gmp_div_qO,  gmp_div_r  ). 


gmp_diV(PHP4>=404) 

Divide  numbers 


resource  gmp_divexact  (resource  a,  resource  b) 


This  function  is  an  alias  to  gmp_div_q  ). 


gmpmod  (php4>=4  0  4) 

Modulo  operation 

resource  gmp_mod  (resource  n,  resource  d) 


Calculates  n  modulo  d.  The  result  is  always  non-negative,  the  sign  of  d  is  ignored. 
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g  m  p_d  i  vexact  (php  4  >=  4  o  4) 

Exact  division  of  numbers 

resource  gmp_di vexact  (resource  n,  resource  d) 


Divides  n  by  d,  using  fast  "exact  division"  algorithm.  This  function  produces  correct  results  only  when  it 
is  known  in  advance  that  d  divides  n. 


gmpcmp  (PHP  4  >=  4.0.4) 

Compare  numbers 

int  gmp_cmp  (resource  a,  resource  b) 


Returns  positive  value  if  a  >  b,  zero  if  a  =  b  and  negative  value  if  a  <  b. 


gmp_neg  (PHP  4  >=  4.0.4) 

Negate  number 

resource  gmp_neg  (resource  a) 


Returns  -a. 


gmp_abs  (PHP  4  >=  4.0.4) 

Absolute  value 

resource  gmp_abs  (resource  a) 


Returns  absolute  value  of  a. 
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gmp_sign  (PHP  4  >=  4.0.4) 

Sign  of  number 

int  gmp_sign  (resource  a) 


Return  sign  of  a  -  1  if  a  is  positive  and  -1  if  it’s  negative. 


gmp_fact  (PHP  4  >=  4.0.4) 

Factorial 

resource  gmp_fact  (int  a) 


Calculates  factorial  (a ! )  of  a. 


gmp_sqrt  (PHP  4  >=4.0.4) 

Square  root 

resource  gmp_sqrt  (resource  a) 


Calculates  square  root  of  a. 


gmpsqrtrm  (unknown) 

Square  root  with  remainder 

array  gmp_sqrtrm  (resource  a) 


Returns  array  where  first  element  is  the  integer  square  root  of  a  (see  also  gmp_sqrt')),  and  the  second  is 
the  remainder  (i.e.,  the  difference  between  a  and  the  first  element  squared). 
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gmp_perfect_square  (php  4  >=  4.o.4) 

Perfect  square  check 

bool  gmp_perfect_square  (resource  a) 

Returns  true  if  a  is  a  prefect  square,  false  otherwise. 

See  also:  gmp_sqrC),  gmp_sqrtrm). 

gmppow  (PHP  4  >=  4.0.4) 

Raise  number  into  power 

resource  gmp_pow  (resource  base,  int  exp) 

Raise  base  into  power  exp.  The  case  of  0A0  yields  1.  exp  cannot  be  negative. 

gmppowm  (PHP  4  >=  4.0.4) 

Raise  number  into  power  with  modulo 

resource  gmp_powm  (resource  base,  resource  exp,  resource  mod ) 

Calculate  ( base  raised  into  power  exp)  modulo  mod.  If  exp  is  negative,  result  is  undefined. 

gmp_prob_prime  (php  4  >=  4  o  4) 

Check  if  number  is  "probably  prime" 

int  gmp_prob_prime  (resource  a  [,  int  reps]) 
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If  this  function  returns  0,  a  is  definitely  not  prime.  If  it  returns  1,  then  a  is  "probably"  prime.  If  it  returns 
2,  then  a  is  surely  prime.  Reasonable  values  of  reps  vary  from  5  to  10  (default  being  10);  a  higher  value 
lowers  the  probability  for  a  non-prime  to  pass  as  a  "probable"  prime. 

The  function  uses  Miller-Rabin’s  probabilistic  test. 


gmp_gcd  (php4>=4  0  4) 


Calculate  GCD 


resource  gmp_gcd  (resource  a,  resource  b) 


Calculate  greatest  common  divisor  of  a  and  b.  The  result  is  always  positive  even  if  either  of  or  both 
input  operands  are  negative. 


gmp_gcdext  <php  4  >=  4  o  4) 

Calculate  GCD  and  multipliers 

array  gmp_gcdext  (resource  a,  resource  b) 

Calculates  g,  s,  and  t,  such  that  a* s  +  b*t  =  g  =  gcd  (a,  b) ,  where  gcd  is  gretest  common  divisor. 
Returns  array  with  respective  elements  g,  s  and  t. 


gmpjnvert  (PHP  4  >=  4.0.4) 

Inverse  by  modulo 

resource  gmp_invert  (resource  a,  resource  b) 


Computes  the  inverse  of  a  modulo  b.  Returns  false  if  an  inverse  does  not  exist. 
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gmpjegendre  (php  4  >=  4 .0 ,4) 

Legendre  symbol 

int  gmp_legendre  (resource  a,  resource  p) 


Compute  the  Legendre  symbol  (http://www.utm.edu/research/primes/glossary/LegendreSymbol.html)  of 
a  and  p.  p  should  be  odd  and  must  be  positive. 


gmp  Jacobi  (php  4  >=  4 .0 .4> 

Jacobi  symbol 

int  gmp_jacobi  (resource  a,  resource  p) 


Computes  Jacobi  symbol  (http://www.utm.edu/research/primes/glossary/JacobiSymbol.html)  of  a  and 
p.  p  should  be  odd  and  must  be  positive. 


gmprandom  (php  4  >=  4  0  4) 

Random  number 

resource  gmp_random  (int  limiter) 


Generate  a  random  number.  The  number  will  be  up  to  limiter  words  long.  If  limiter  is  negative, 
negative  numbers  are  generated. 

gmp_and  (PHP  4  >=  4.0.4) 

Logical  AND 

resource  gmp_and  (resource  a,  resource  b) 

Calculates  logical  AND  of  two  GMP  numbers. 
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gmpor  (PHP  4  >=  4.0.4) 

Logical  OR 

resource  gmp_or  (resource  a,  resource  b) 

Calculates  logical  inclusive  OR  of  two  GMP  numbers. 

gmp_xor  (PHP  4  >=  4.0.4) 

Logical  XOR 

resource  gmp_xor  (resource  a,  resource  b) 

Calculates  logical  exclusive  OR  (XOR)  of  two  GMP  numbers. 

gmp_setbit(PHP4>=4  0  4) 

Set  bit 

resource  gmp_setbit  (resource  &a,  int  index  [,  bool  set_clear]) 

Sets  bit  index  in  a.  set_clear  defines  if  the  bit  is  set  to  0  or  1.  By  default  the  bit  is  set  to  1. 

gmp_clrbit(PHP4>=4  0  4) 

Clear  bit 

resource  gmp_clrbit  (resource  &a,  int  index) 

Clears  (sets  to  0)  bit  index  in  a. 
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gmpscanO  (php  4  >=  4  o  4) 

Scan  for  0 

int  gmp_scanO  (resource  a,  int  start) 

Scans  a,  starting  with  bit  start,  towards  more  significant  bits,  until  the  first  clear  bit  is  found.  Returns 
the  index  of  the  found  bit. 

gmpscanl  (php4>=4o4) 

Scan  for  1 

int  gmp_scanl  (resource  a,  int  start ) 

Scans  a,  starting  with  bit  start,  towards  more  significant  bits,  until  the  first  set  bit  is  found.  Returns  the 
index  of  the  found  bit. 

gmp_popcount  (PHP  4  >=  4.0.4) 

Population  count 

int  gmp_popcount  (resource  a) 

Return  the  population  count  of  a. 

gmphamdist  <php  4  >=  4 .0 ,4) 

Hamming  distance 

int  gmp_hamdist  (resource  a,  resource  b) 

Returns  the  hamming  distance  between  a  and  a.  Both  operands  should  be  non-negative. 
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Estas  funciones  permiten  manipular  la  salida  que  se  envfa  al  navegador  remoto  a  nivel  de  protocolo 
HTTP. 


400 


HTTP 


header  (PHP  3,  PHP  4  >=  4.0.0) 

Manda  una  cabecera  HTTP 

int  header  (string  string) 


La  funcion  header()  se  utiliza  al  comienzo  de  un  fichero  HTML  para  enviar  las  cadenas  de  texto  de  la 
cabecera  HTTP.  Consulte  la  Especificacion  HTTP  1.1  (http://www.w3.org/Protocols/rfc2616/rfc2616) 
para  obtener  mas  information  sobre  las  cabeceras  http.  Not  a:  Recuerde  que  la  funcion  header()  debe 
llamarse  antes  de  que  se  genere  salida  alguna,  bien  con  etiquetas  HTML  normales  o  con  PHP.  Un  error 
muy  frecuente  consiste  en  leer  codigo  con  include  )  o  con  auto_prepend,  y  que  dicho  codigo  inserte 
espacios  o  lmeas  en  bianco  antes  de  llamar  a  headerQ. 

Hay  dos  casos  especiales  de  llamadas  a  header.  La  primera  es  la  cabecera  "Location".  No  solo  envfa  esta 
cabecera  al  navegador,  sino  que  tambien  devuelve  un  codigo  de  estado  REDIRECT  a  Apache.  Desde  el 
punto  de  vista  del  programador  de  scripts  esto  no  deberfa  ser  importante,  pero  para  la  gente  que 
comprende  las  interioridades  de  Apache  sf  puede  serlo. 

header ( "Location :  http://www.php.net");  /*  Redirect  browser  to  PHP  web  site  */ 
exit;  /*  Make  sure  that  code  below  does  not  get  executed  when  we  redirect.  */ 


El  segundo  caso  especial  se  produce  con  cualquier  cabecera  que  comience  con  la  cadena,  "HTTP/"  (las 
mayusculas  no  son  significativas).  Por  ejemplo,  si  tiene  la  directiva  ErrorDocument  404  de  Apache 
apuntando  a  un  script  PHP,  es  una  buena  idea  asegurarse  de  que  su  script  de  PHP  genera  realmente  un 
404.  La  primera  cosa  que  debe  hacer  en  su  script  serfa: 

header ( "http/1 . 0  404  Not  Found"); 


Los  scripts  de  PHP  a  menudo  generan  HTML  dinamico  que  no  debe  almacenarse  en  la  cache  del 
navegador  cliente  o  en  la  cache  de  cualquier  proxy  situado  entre  el  servidor  y  el  navegador  cliente.  Se 
puede  obligar  a  muchos  proxies  y  clientes  a  que  deshabiliten  el  almacenamiento  en  cache  con 


header ( "Expires :  Mon,  26  Jul  1997  05:00:00  GMT"); 
header ( "Last-Modified:  "  .  gmdate("D,  d  M  Y  H:i:s") 
header ( "Cache-Control :  no-cache,  must-revalidate " ) ; 
header ( "Pragma :  no-cache") ; 


/ /  Date  in  the  past 
"  GMT");  //  always  modified 
//  HTTP/1.1 
//  HTTP/1.0 


401 


HTTP 


setcookie  (PHP  3,  PHP  4  >=  4.0.0) 


Envfa  una  cookie 


int  setcookie  (string  name,  string  value,  int  expire,  string  path,  string 
domain,  int  secure) 


setcookie()  define  una  cookie  para  ser  enviada  con  el  resto  de  la  information  de  la  cabecera.  Las  cookies 
deben  enviarse  antes  de  mandar  cualquier  otra  cabecera  (esta  es  una  restriction  de  las  cookies,  no  de 
PHP).  Esto  requiere  que  situe  las  llamadas  a  esta  funcion  antes  de  cualquier  etiqueta  <html>  o  <head>. 

Todos  los  parametros  excepto  name  son  opcionales.  Si  solo  se  especifica  el  parametro  name,  la  cookie 
con  ese  nombre  se  borrara  del  cliente  remoto.  Tambien  puede  sustituir  cualquier  parametro  por  una 
cadena  de  texto  vacfa  ("")  y  saltar  asf  ese  parametro.  Los  parametros  expire  y  secure  son  numeros 
enteros  y  no  se  pueden  saltar  con  una  cadena  de  texto  vacfa.  En  su  lugar  utilice  un  cero  ( 0 ).  El  parametro 
expire  es  un  entero  de  tiempo  tfpico  de  UNIX  tal  como  lo  devuelven  las  funciones  time ')  o  mktime '). 
El  parametro  secure  indica  que  la  cookie  se  debe  transmitir  unica  y  exclusivamente  sobre  una 
conexion  segura  HTTPS. 

Fallos  habituales: 

Las  cookies  no  se  hacen  visibles  hasta  la  siguiente  carga  de  una  pagina  para  la  que  la  cookie  deba  estar 
visible. 

Las  llamadas  multiples  a  setcookie()  en  el  mismo  script  se  ejecutaran  en  orden  inverso.  Si  esta  intentando 
borrar  una  cookie  antes  de  insertar  otra,  debe  situar  la  llamada  de  insertion  antes  de  la  de  borrado. 

A  continuation  se  muestran  algunos  ejemplos:: 

Ejemplo  1.  setcookie)),  ejemplos 

setcookie ("TestCookie",  "Test  Value") ; 

setcookie ( "TestCookie" , $value, time () +3600 ) ;  /*  expire  in  1  hour  */ 

setcookie  ("TestCookie", $ value, time ( ) +3600 , " /-rasmus/ " , " . ut or onto . ca"  ,  1 ) ; 


Tenga  en  cuenta  que  el  campo  value  de  la  cookie  se  codifica  como  URL  (urlencode)  automaticamente 
cuando  envfa  la  cookie.  Cuando  esta  se  recibe,  se  descodifica  automaticamente  y  se  asigna  a  una  variable 
con  el  mismo  nombre  que  el  nombre  de  la  cookie.  Para  ver  el  contenido  de  nuestra  cookie  de  prueba  en 
un  script,  simplemente  utilice  uno  de  los  siguientes  ejemplos: 

echo  $TestCookie; 

echo  $HTTP_COOKIE_VARS [ "TestCookie" ] ; 


Tambien  puede  utilizar  arrays  de  cookies  empleando  la  notation  de  array  en  el  nombre  de  la  cookie.  Esto 
tiene  como  efecto  establecer  tantas  cookies  como  elementos  de  array,  pero  cuando  el  script  recibe  la 
cookie,  se  guardan  los  valores  en  un  array  con  el  nombre  de  la  cookie: 
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setcookie  (  " cookie [three ]" ,  " cookiethree "  ); 

setcookie  (  " cookie [two ]" ,  "cookietwo"  ); 
setcookie  (  "cookie [one] " ,  "cookieone"  ); 
if  (  isset  (  $cookie  )  )  { 

while  (  list  (  $name,  $value  )  =  each (  $cookie  )  )  { 

echo  "$name  ==  $value<br>\n" ; 


} 


Para  obtener  mas  information  sobre  las  cookies,  consulte  la  especificacion  de  cookies  de  Netscape,  que 
se  encuentra  en  http://www.netscape.com/newsref/std/cookie_spec.html. 

Microsoft  Internet  Explorer  4  con  Service  Pack  1  no  funciona  correctamente  con  las  cookies  que  tienen 
asociado  el  parametro  path. 

Netscape  Communicator  4.05  y  Microsoft  Internet  Explorer  3.x  funcionan  aparentemente  de  manera 
incorrecta  cuando  no  se  especifican  los  parametros  path  y  time. 
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XXXIII.  Funciones  para  Hyperwave 


Introduccion 


Hyperwave  ha  sido  desarrollado  en  el  IICM  (http://www.iicm.edu)  en  Graz.  Comenzo  con  el  nombre 
Hyper-G  y  cambio  a  Hyperwave  cuando  fue  comercializado  (Si  lo  recuerdo  bien,  fue  en  1996). 

Hyperwave  no  es  software  gratuiro.  La  version  actual,  4.1,  esta  disponible  en  www.hyperwave.com 
(http://www.hyperwave.com/).  Se  puede  solicitar  gratuitamente  una  version  limitada  (30  dfas). 

Hyperwave  es  un  sistema  de  informacion  similar  a  una  base  de  datos  (HIS,  Hyperwave  Information 
Server  -  Servidor  Hyperwave  de  Informacion).  Su  objetivo  es  el  almacenamiento  y  manipulation  de 
documentos.  Un  documento  puede  ser  cualquier  bloque  posible  de  datos  que  tambien  puede  ser 
almacenado  en  un  archivo.  Cada  documento  se  acompana  por  su  registro  de  objeto.  El  registro  de  objeto 
contiene  metadatos  para  el  documento.  Los  metadatos  son  una  lista  de  atributos  que  pueden  ser 
extendidos  por  el  usuario.  Ciertos  atributos  siempre  son  fijados  por  el  servidor  Hyperwave,  otros  pueden 
ser  modificados  por  el  usuario.  Un  atributo  es  un  par  nombre/valor  de  la  forma  nombre=valor.  El  registro 
completo  del  objeto  tiene  tantos  de  estos  pares  como  guste  el  usuario.  El  nombre  de  un  atributo  no  tiene 
porque  ser  unico,  p.  ej.  un  tftulo  puede  aparecer  varias  veces  en  el  registro  de  un  objeto.  Esto  tiene 
sentido  si  se  desea  especificar  un  tftulo  en  diferentes  idiomas.  En  dicho  caso  existe  la  convention  de  que 
cada  valor  de  tftulo  este  precedido  por  la  abreviatura  de  dos  letras  del  idioma,  seguida  por  dos  puntos, 
como  p.  ej.  ’en:Title  in  English’  o  ’es:Tftulo  en  EspanoF.  Otros  atributos  tales  como  descripciones  o 
palabras  clave  son  canditatos  potenciales  a  esta  diferenciacion.  Tambien  se  pueden  reemplazar  las 
abreviaturas  de  idioma  por  cualquier  otra  cadena  siempre  y  cuando  esten  separadas  por  los  dos  puntos 
del  resto  del  valor  del  atributo. 

Cada  registro  de  objeto  tiene  una  representacion  nativa  como  cadena  con  cada  par  nombre/valor  separado 
por  una  lfnea  nueva.  La  extension  Hyperwave  tambien  conoce  una  segunda  representacion  que  consiste 
en  un  array  asociativo  donde  el  nombre  del  atributo  es  la  clave.  Los  valores  de  atributo  multilingiies  en  sf 
mismos  forman  otro  array  asociativo  donde  la  clave  es  la  abreviatura  del  idioma.  Realmente  cualquier 
atributo  multiple  forma  una  tabla  asociativa  donde  la  cadena  a  la  izquierda  de  los  dos  puntos  en  el  valor 
de  atributo  es  la  clave.  (Esto  no  se  ha  implementado  por  completo.  Solo  los  atributos  Title,  Description  y 
Keyword  son  tratados  adecuadamente.) 

Aparte  de  los  documentos,  todos  los  hiper-enlaces  contenidos  en  un  documento  son  almacenados 
tambien  como  registros  de  objeto.  Cuando  el  documento  sea  insertado  en  la  base  de  datos,  los 
hiper-enlaces  que  haya  en  un  documento  seran  borrados  del  mismo  y  almacenados  como  objetos 
individuales.  El  registro  de  objeto  del  enlace  contiene  informacion  acerca  de  donde  comienza  y  donde 
termina.  Para  recuperar  el  documento  original  se  debera  recuperar  el  documento  sin  los  enlaces  y  la  lista 
de  los  mismos  para  reinsertarla  (Las  funciones  hw_pipedocument')  y  hw_gettextO  hacen  esto  para 
usted).  La  ventaja  de  separar  los  enlaces  del  documento  es  obvia.  Una  vez  un  documento  al  que  apunta 
un  enlace  cambia  de  nombre,  el  enlace  puede  modificarse  facilmente.  El  documento  que  contiene  el 
enlace  no  se  ve  afectado.  Incluso  se  puede  anadir  un  enlace  a  un  documento  sin  alterarlo. 

Decir  que  hw_pipedocument()  y  hw_gettext')  hacen  automaticamente  la  insertion  de  enlaces  no  es  tan 
simple  como  suena.  Insertar  los  enlaces  implica  una  cierta  jerarqufa  en  los  documentos.  En  un  servidor 
web  esto  viene  dado  por  el  sistema  de  archivos,  pero  el  Hyperwave  tiene  su  propia  jerarqufa  y  los 
nombres  no  representan  la  position  de  un  objeto  en  dicha  jerarqufa.  Por  tanto,  la  creacion  de  los  enlaces 
precisa  primeramente  de  realizar  un  mapeado  entre  el  espacio  de  nombres  y  la  jerarqufa  del  Hyperwave  y 
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el  espacio  de  nombres  respectivo  de  una  jerarqma  de  web.  La  diferencia  fundamental  entre  Hyperwave  y 
la  web  es  la  distincion  clara  entre  nombres  y  jerarqma  que  se  da  en  el  primero.  El  nombre  no  contiene 
ninguna  informacion  sobre  la  posicion  del  objeto  en  la  jerarqma.  En  la  web,  el  nombre  tambien  contiene 
la  informacion  sobre  la  posicion  en  la  jerarqma  del  objeto.  Esto  nos  lleva  a  dos  posibles  formas  de 
mapeo.  O  bien  se  reflejan  la  jerarqma  del  Hyperwave  y  el  nombre  del  objeto  Hyperwave  en  el  URL  o 
solo  el  nombre.  Para  facilitar  las  cosas,  se  utiliza  el  segundo  metodo.  El  objeto  Hyperwave  de  nombre 
’mi_objeto’  es  mapeado  a  ’http://host/mi_objeto’  sin  importar  donde  reside  dentro  de  la  jerarqma  de 
Hyperwave.  Un  objeto  con  el  nombre  ’padre/mi_objeto’  podrfa  ser  el  hijo  de  ’mi_objeto’  en  la  jerarqma 
Hyperwave,  aunque  en  el  espacio  de  nombres  web  aparezca  justamente  lo  opuesto  y  el  usuario  pueda  ser 
llevado  a  confusion.  Esto  solo  se  puede  evitar  seleccionando  nombres  de  objetos  razonables. 

Hecha  esta  decision  surge  un  segundo  problema.  ('  C6mo  implicar  al  PHP?  el  URL  http://host/mi_objeto 
no  llamara  a  ningun  script  PHP  a  no  ser  que  se  le  diga  al  servidor  que  lo  transforme  en  p.  ej. 
’http://host/script_php3/mi_objeto’  y  que  el  ’script_php3’  luego  evalue  la  variable  $PATH_INFO  y 
recupere  el  objeto  con  nombre  ’mi_objeto’  del  servidor  Hyperwave.  Hay  solo  un  pequeno  inconveniente 
que  se  puede  resolver  facilmente.  Cuando  se  reescribe  cualquier  URL  no  se  permite  el  acceso  a  ningun 
otro  documento  en  el  servidor  web.  Un  script  de  PHP  para  buscar  en  el  servidor  Hyperwave  serfa 
imposible.  Por  lo  tanto  se  necesitara  al  menos  una  segunda  regia  de  reescritura  para  que  excluya  ciertos 
URL,  como  los  que  empiecen  p.  ej.  por  http://host/Hyperwave.  Basicamente  esto  serfa  compartir  un 
espacio  de  nombres  entre  el  servidor  web  y  el  servidor  Hyperwave. 

Los  enlaces  se  insertan  en  los  documentos  basandose  en  el  mecanismo  citado  mas  arriba. 

Se  vuelve  mas  complicado  si  el  PHP  no  se  esta  ejecutando  como  modulo  del  servidor  o  como  script  CGI, 
sino  que  se  ejecuta  como  aplicacion,  p.  ej.  para  volcar  el  contenido  del  servidor  de  Hyperwave  a  un 
CD-ROM.  En  dicho  caso  tiene  sentido  mantener  la  jerarqma  Hyperwave  y  mapearla  en  el  sistema  de 
archivos.  Esto  entra  conflicto  con  los  nombres  de  los  objetos  si  estos  reflejan  su  propia  jerarqma  (p.  ej. 
eligiendo  nombres  que  comienzan  por  ’/’).  Por  tanto,  la  7’  tendra  que  ser  reemplazada  por  otro  caracter, 
p.  ej.  para  continuar. 

El  protocolo  de  red  para  comunicarse  con  el  servidor  Hyperwave  se  denomina  HG-CSP 
(http://www.hyperwave.de/?.  17-hg-prot)  (Hyper-G  Client/Server  Protocol,  Protocolo  Hyper-G 
Cliente/Servidor).  Esta  basado  en  mensajes  que  inician  ciertas  acciones,  p.  ej.  obtener  el  registro  de  un 
objeto.  En  versiones  anteriores  del  Servidor  Hyperwave  se  distribuyeron  dos  clientes  nativos  (Harmony, 
Amadeus)  para  la  comunicacion  con  el  servidor.  Ambos  desaparecieron  cuando  se  comercializo  el 
Hyperwave.  Para  sustitufrlo  se  proporciono  el  llamado  wavemaster.  El  wavemaster  es  como  un  conversor 
de  protocolo  de  HTTP  a  HG-CSP.  La  idea  es  realizar  toda  la  administration  de  la  base  de  datos  y  la 
visualization  de  documentos  con  una  interfaz  web.  El  wavemaster  implementa  una  serie  de 
posicionadores  para  acciones  que  permiten  personalizar  la  interfaz.  Dicho  conjunto  de  posicionadores  se 
denomina  el  Lenguaje  PLACE.  El  PLACE  no  posee  muchas  de  las  caracterfsticas  de  un  lenguaje  de 
programacion  real  y  las  extensiones  al  mismo  unicamente  alargan  la  lista  de  posicionadores.  Esto  ha 
obligado  al  uso  de  JavaScript  que,  en  mi  opinion,  no  hace  la  vida  mas  facil. 

Anadir  soporte  de  Hyperwave  al  PHP  rellenarfa  el  espacio  que  deja  la  falta  de  un  lenguaje  de 
programacion  que  permita  personalizar  la  interfaz.  El  PHP  implementa  todos  los  mensajes  definidos  en 
el  HG-CSP  pero  ademas  proporciona  comandos  mas  poderosos,  p.  ej.  recuperar  documentos  completos. 

El  Hyperwave  tiene  su  propia  terminologfa  para  dar  nombre  a  ciertos  tipos  de  informacion.  Esta  ha  sido 
ampliamente  extendida  y  anulada.  Casi  todas  las  funciones  operan  en  uno  de  los  siguientes  tipos  de 
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datos. 

•  ID  de  objeto:  Un  valor  entero  linico  paara  cada  objeto  del  servidor  Hyperwave.  Tambien  es  uno  de  los 
atributos  del  registro  de  objeto  (ObjectID).  Los  ID  de  objeto  se  usan  generalmente  como  parametros 
de  entrada  que  especifican  a  un  objeto. 

•  registro  de  objeto:  Una  cadena  con  pares  atributo-valor  con  la  forma  atributo=valos.  Los  pares  estan 
separados  unos  de  otros  por  un  retorno  de  carro.  Un  registro  de  objeto  puede  convertirse  facilmente  en 
una  tabla  (array)  de  objetos  usando  hw_object2array().  Varias  funciones  devuelven  registros  de 
objeto.  Los  nombres  de  dichas  funciones  terminan  en  obj. 

•  tabla  de  objetos:  Una  tabla  asociativa  con  todos  los  atributos  de  un  objeto.  La  clave  es  el  nombre  del 
atributo.  Si  un  atributo  aparece  mas  de  una  vez  en  un  registro  de  objeto  sera  convertido  en  otra  tabla 
asociativa  o  indizada.  Los  atributos  que  dependen  del  idioma  (como  el  tltulo,  claves  o  description)  se 
convertiran  en  una  tabla  asociativa  con  la  abreviatura  del  idioma  como  clave.  El  resto  de  los  atributos 
multiples  crearan  una  tabla  indizada.  Las  funciones  de  PHP  nunca  devuelven  tablas  de  objetos. 

•  hw_document:  Este  es  un  nuevo  tipo  de  datos  que  almacena  el  documento  actual,  p.  ej.  HTML,  PDF, 
etc.  Esta  algo  optimizado  para  documentos  HTML  pero  puede  usarse  para  cualquier  formato. 


Varias  funciones  que  devuelven  una  tabla  de  registros  de  objeto  tambien  devuelven  una  tabla  asociativa 
con  information  estadlstica  sobre  los  mismos.  La  tabla  es  el  ultimo  elemento  del  registro  de  objeto.  La 
tabla  estadlstica  contiene  los  siguientes  elementos: 


Hidden 


Numero  de  registros  de  objeto  con  el  atributo  PresentationHints  puesto  a  Hidden. 


CollectionHead 

Numero  de  registros  de  objeto  con  el  atributo  PresentationHints  puesto  a  CollectionHead. 
FullCollectionHead 

Numero  de  registros  de  objeto  con  el  atributo  PresentationHints  puesto  a  FullCollectionHead. 


CollectionHeadNr 

Indice  a  una  tabla  de  regitros  de  objeto  con  el  atributo  PresentationHints  puesto  a  CollectionHead. 
FullCollectionHeadNr 

Indice  a  una  tabla  de  regitros  de  objeto  con  el  atributo  PresentationHints  puesto  a 
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FullCollectionHead. 


Total 


Total:  Numero  de  registros  de  objeto. 


Integracion  con  Apache 

La  extension  Hyperwave  se  utiliza  mejor  cuando  el  PHP  se  compila  como  un  modulo  de  Apache.  En  tal 
caso  el  servidor  Hyperwave  subyacente  puede  ser  ocultado  casi  por  completo  de  los  usuarios  si  el 
Apache  utiliza  su  motor  de  re-escritura.  Las  siguientes  instrucciones  explicaran  esto. 

Como  el  PHP  con  soporte  Hyperwave  inclufdo  en  el  Apache  se  ha  disenado  para  sustituir  la  solution 
nativa  de  Hyperwave  basada  en  Wavemaster,  asumire  que  el  servidor  Apache  solo  sirve  como  interfaz 
web  para  el  Hyperwave.  Esto  no  es  necesario,  pero  simplifica  la  configuration.  El  concepto  es  bastante 
sencillo.  Primeramente  necesita  un  script  PHP  que  evalue  la  variable  PATH_INFO  y  que  trate  su  valor 
como  el  nombre  de  un  objeto  Hyperwave.  Llamemos  a  este  script  ’Hyperwave’.  El  URL 
http://nombre.servidor/Hyperwave/nombre_de_objeto  devolverfa  entonces  el  objeto  Hyperwave  llamado 
’nombre_de_objeto’.  Dependiendo  del  tipo  del  objeto,  asf  reactionary  el  script.  Si  es  una  coleccion, 
probablemente  devolvera  un  lista  de  hijos.  Si  es  un  documento  devolvera  el  tipo  MIME  y  el  contenido. 

Se  puede  mejorar  ligeramente  si  se  usa  el  motor  de  re-escritura  del  Apache.  Desde  el  punto  de  vista  del 
usuario  sera  mas  sencillo  si  el  URL  http://nombre.servidor/nombre  de  objeto  devuelve  el  objeto.  La  regia 
de  reescritura  es  muy  sencilla: 

RewriteRule  A/(.*)  /usr/local/apache/htdocs/HyperWave/$l  [L] 

Ahora  todo  URL  apunta  a  un  objeto  en  el  servidor  Hyperwave.  Esto  provoca  un  problema  sencillo  de 
resolver.  No  hay  forma  de  ejecutar  otro  script,  p.  ej.  para  buscar,  salvo  el  script  ’Hyperwave’.  Esto  se 
puede  solucionar  con  otra  regia  de  reescritura  como  la  siguiente: 

RewriteRule  A/hw/(.*)  /usr/local/apache/htdocs/hw/$l  [L] 

Esta  reservara  el  directorio  /usr/local/apache/htdocs/hw  para  script  adicionales  y  otros  archivos. 
Solo  hay  que  asegurarse  que  esta  regia  se  evalua  antes  de  la  otra.  Solo  hay  un  pequeno  inconveniente: 
todos  los  objetos  Hyperwave  cuyo  nombre  comienza  por  ’hw/’  seran  ocultados.  asf  que  asegurese  que  no 
utiliza  dichos  nombres.  Si  necesita  mas  directorios,  p.  ej.  para  imagenes,  simplemente  anada  mas  reglas  o 
situe  los  archivos  en  un  solo  directorio.  Por  ultimo,  no  olvide  conectar  el  motor  de  re-escritura  con 


RewriteEngine  on 
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Mi  experiencia  me  ha  demostrado  que  necesitara  los  siguientes  scripts: 


•  para  devolver  el  script  en  si 

•  para  permitir  las  busquedas 

•  para  identificarse 

•  para  ajustar  su  perfil 

•  uno  para  cada  funcion  adicional  como  mostrar  los  atributos  del  objeto,  mostrar  information  sobre 
usuarios,  mostrar  el  estado  del  servidor,  etc. 


Pendientes 


Aun  hay  varias  cos  as  pendientes: 


•  hw_InsertDocument  debe  dividirse  en  hw_InsertObject()  y  hw_PutDocument(). 

•  Los  nombres  de  algunas  funciones  aun  no  estan  fijados. 

•  Muchas  funciones  precisan  la  conexion  actual  como  primer  parametro.  Esto  obliga  a  escribir  mucho, 
lo  cual  no  es  con  frecuencia  necesario  si  solo  hay  una  conexion  abierta.  Una  conexion  por  defecto 
mejorana  esto. 

•  La  conversion  de  registro  de  objeto  a  tabla  de  objeto  necesita  manipular  cualquier  atributo  multiple. 
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hw_Array20bjrec  (PHP  3>=  3.0.4,  PHP  4  >=  4.0.0) 

convierte  atributos  de  tabla  de  objeto  a  registro  de  objeto 

strin  hw_array2ob jrec  (array  tabla_objetos) 

Convierte  una  tabla_objetos  en  un  registro  de  objeto.  Los  atributos  multiples  como  ’Tltulo’  en 
distintos  idiomas  son  tratados  correctamente. 

Vea  tambien  h  w_obj  rec  2array j . 

hwChildren  (PHP  3>=  3.0.3,  PHP  4  >=  4.0.0) 
id  de  objeto  de  los  hijos 

array  hw_children  (int  conexion,  int  IDobjeto) 


Devuelve  una  tabla  de  id  de  objeto.  Cada  uno  de  ellos  pertenece  a  un  hijo  de  la  coleccion  cuyo  ID  es 
IDobjeto.  La  tabla  contiene  tanto  los  documentos  como  las  colecciones  hijas. 


hwChildrenObj  (PHP  3>=  3.0.3,  PHP  4  >=  4.0.0) 

registros  de  objeto  de  los  hijos 

array  hw_childrenob j  (int  conexion,  int  IDobjeto) 


Devuelve  una  tabla  de  registros  de  objeto.  Cada  uno  de  ellos  pertenece  a  un  hijo  de  la  coleccion  cuyo  ID 
es  IDobjeto.  La  tabla  contiene  tanto  los  documentos  como  las  colecciones  hijas. 


hwClose  (PHP  3>=  3.0.3,  PHP  4  >=  4.0.0) 
cierra  la  conexion  Hyperwave 

int  hw_close  (int  conexion) 
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Devuelve  false  si  la  conexion  no  es  un  fndice  valido  de  conexion,  y  true  en  caso  contrario.  Cierra  la 
conexion  dada  con  el  servidor  de  Hyperwave. 


hwConnect  (PHP  3>=  3.0.3,  PHP  4  >=  4.0.0) 


abre  una  conexion 


int  hw_connect  (string  servidor ,  int  puerto, 


string  usuario, 


string  clave) 


Abre  una  conexion  con  un  servidor  Hyperwave  y  devuelve  un  fndice  de  conexion  si  hay  exito,  o  false 
si  la  conexion  no  se  pudo  realizar.  Cada  argumento  debe  ser  una  cadena  entrecomillada  salvo  el  numero 
de  puerto.  Los  argumentos  de  usuario  y  clave  son  opcionales  y  pueden  omitirse.  En  tal  caso  no  se 
realizara  identificacion  alguna  con  el  servidor.  Es  similar  a  identificarse  como  el  usuario  ’anonymous’. 
Esta  funcion  devuelve  un  fndice  de  conexion  que  se  necesita  para  otras  funciones  Hyperwave.  Puede 
tener  varias  conexiones  abiertas  a  la  vez.  Recuerde  que  la  clave  no  esta  encriptada. 

Vea  tambien  hw_pConnect(). 


hwCp  (php 


3>=  3.0.3,  PHP  4  >=  4.0.0) 


copia  objetos 


int  hw_cp  (int  conexion,  array  tabla_id_objeto,  int  id  destino) 


Copia  los  objetos  cuyos  id  se  especifican  en  el  segundo  parametro  a  la  coleccion  identificada  como  id 

destino. 

El  valor  devuelto  es  el  numero  de  objetos  copiados. 

Vea  tambien  hw_mv(). 


hw_Deleteobject  (PHP  3>=  3.0.3,  PHP  4  >=  4.0.0) 

borra  objetos 

int  hw_deleteob ject  (int  conexion,  int  objeto_a_borrar) 


Borra  el  objeto  con  el  id  dado  como  segundo  parametro.  Borrara  todas  las  instancias  del  mismo. 
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Devuelve  true  si  no  hay  error  o  false  en  caso  contrario. 

Vea  tambien  hw_mv '). 

hwDocByAnchor  (php  3>=  3.0.3,  php  4  >=  4  0  o> 

id  del  objeto  al  que  pertenece  un  enlace 

int  hw_docbyanchor  (int  conexidn,  int  IDenlace) 

Devuelve  el  id  de  objeto  del  documento  al  que  pertenece  el  IDenlace. 

hwDocByAnchorObj  (PHP  3>=  3.0.3,  PHP  4  >=  4.0.0) 

registro  de  objeto  al  que  pertenece  un  enlace 

string  hw_docbyanchorob j  (int  conexidn,  int  IDenlace) 

Devuelve  el  registro  de  objeto  del  documento  al  que  pertenece  el  IDenlace. 

hwDocumentAttributes  (php  3>=  3.0.3) 

registro  de  objeto  de  un  documento_hw 

string  hw_documentattributes  (int  documento_hw) 

Devuelve  el  registro  de  objeto  del  documento  dado. 

Vea  tambien  hw_DocumentBodyTag(),  hw_DocumentSize(). 

hwDocumentBodyTag  (phps>=  3.0.3) 

marca  ’BODY’  de  un  documento_hw 
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string  hw_documentbodytag  (int  documento_hw ) 


Devuelve  la  marca  BODY  del  documento.  Si  el  documento  es  de  tipo  HTML  la  etiqueta  BODY  debera 
imprimirse  antes  que  el  documento. 

Vea  tambien  hw_DocumentAttributes(),  hw_DocumentSize(). 


hwDocumentContent  (PHP  3>=  3.0.8) 

devuelve  el  contenido  de  un  documento_hw 


string  hw_documentcontent  (int  documento_hw) 


Devuelve  el  contenido  del  documento.  Si  el  documento  es  de  tipo  HTML  el  contenido  es  todo  lo  que  hay 
tras  la  etiqueta  BODY.  La  informacion  de  las  etiquetas  HEAD  y  BODY  se  almacenan  en  el  registro  de 
objeto. 

Vea  tambien  hw_DocumentAttributes(),  hw_DocumentSize(),  hw_DocumentSetContent(). 


hwDocumentSetContent  (PHP  3>=  3.0.8) 


fija/sustituye  el  contenido  de  un  documento_hw 


string  hw_documentsetcontent  (int  documento_hw ,  string  contenido) 


Fija  o  sustituye  el  contenido  del  documento.  Si  el  documento  es  de  tipo  HTML  el  contenido  es  todo  lo 
que  hay  tras  la  etiqueta  BODY.  La  informacion  de  las  etiquetas  HEAD  y  BODY  se  almacenan  en  el 
registro  de  objeto.  Si  proporciona  tambien  esta  informacion  en  el  contenido  del  documento,  el  servidor 
Hyperwave  modificara  el  registro  del  objeto  cuando  sea  insertado  el  documento.  Probablemente  no  es 
una  buena  idea.  Si  esta  funcion  falla,  el  documento  retendra  su  anterior  contenido. 

Vea  tambien  hw_DocumentAttributes(),  hw_DocumentSize(),  hw_DocumentContent(). 


hwDocumentSize  (PHP  3>=  3.0.3) 


tamano  de  un  documento_hw 


int  hw_documentsize  (int  documento_hw ) 
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Devuelve  el  tamano  en  bytes  del  documento. 

Vea  tambien  hw_DocumentBodyTag(),  hw_DocumentAttributes(). 


hwErrorMsg  (PHP  3>=  3.0.3,  PHP  4  >=  4.0.0) 

devuelve  un  mensaje  de  error 

string  hw_errormsg  (int  conexidn) 

Devuelve  una  cadena  que  contiene  el  ultimo  mensaje  de  error  o  ’No  Error’.  Si  devuelve  false  es  que  la 
funcion  fracaso.  El  mensaje  esta  relacionado  con  el  ultimo  comando. 


hwEditText  (PHP  3>=  3.0.3,  PHP  4  >=  4.0.0) 
recupera  documento  de  texto 

int  hw_edittext  (int  conexidn,  int  documento_hw) 


Envia  el  documento  de  texto  al  servidor.  El  registro  de  objeto  del  documento  no  puede  ser  modificado 
mientras  el  documento  es  editado.  Esta  funcion  solo  funcionara  para  objetos  puros  de  texto.  No  abrira 
ninguna  conexion  especial  de  datos  y  por  tanto  bloquea  la  conexidn  de  control  durante  la  transferencia. 

Vea  tambien  hw_PipeDocument(),  hw_FreeDocument(),  hw_DocumentBodyTag(), 
hw_DocumentSize(),  hw_OutputDocument(),  hw_GetText(). 


hwError  (PHP  3>=  3.0.3,  PHP  4  >=  4.0.0) 
numero  de  error 

int  hw_error  (int  conexidn ) 


Devuelve  el  ultimo  numero  de  error.  Si  el  valor  devuelto  es  0  no  ha  habido  errores.  El  error  esta 
relacionado  con  el  ultimo  comando. 
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hw_Free_Document  (php  3>=  3.0.3,  php  4  >=  4.0.0 

libera  un  documento_hw 

int  hw_f ree_document  (int  documento_hw) 


Libera  la  memoria  ocupada  por  el  documento  Hyperwave. 


hwGetParents  (PHP  3>=  3.0.3,  PHP  4  >=  4.0.0) 

id  de  objeto  de  los  padres 

array  hw_getparentsob j  (int  conexion,  int  IDobjeto) 


Devuelve  una  tabla  indizada  de  id  de  objeto.  Cada  una  pertenece  a  un  padre  del  objeto  con  ID 

IDobjeto. 


hw_GetParentsObj  (PHP  3>=  3.0.3,  PHP  4  >=  4.0.0) 

registros  de  objeto  de  los  padres 

array  hw_getparentsob j  (int  conexion,  int  IDobjeto ) 


Devuelve  una  tabla  indizada  de  registros  de  objeto  junto  a  una  tabla  asociativa  con  information 
estadfstica  sobre  estos.  La  tabla  asociativa  es  el  ultimo  elemento  de  la  tabla  devuelta.  Cada  registro  de 
objeto  pertenece  a  un  padre  del  objeto  con  ID  IDobjeto. 


hwGetChildColl  (PHP  3>=  3.0.3,  PHP  4  >=  4.0.0) 

id  de  objeto  de  colecciones  hijas 

array  hw_getchildcoll  (int  conexion,  int  IDobjeto ) 
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Devuelve  una  tabla  de  id  de  objeto.  Cada  ID  de  objeto  pertenece  a  una  coleccion  hija  de  la  coleccion  con 
ID  IDobjeto.  La  funcion  no  devolvera  documentos  hijos. 

Vea  tambien  hw_GetChildren(),  hw_GetChildDocColl(). 


hw  GetChildCollObj  (PHP  3>=  3.0.3,  PHP  4  >=  4.0.0) 

registros  de  objeto  de  colecciones  hijas 

array  hw_getchildcollob j  (int  conexion,  int  IDobjeto) 

Devuelve  una  tabla  de  registros  de  objeto.  Cada  uno  de  ellos  pertenece  a  una  coleccion  hija  de  la 
coleccion  con  ID  IDobjeto.  La  funcion  no  devolvera  documentos  hijos. 

Vea  tambien  hw_ChildrenObj(),  hw_GetChildDocCollObj(). 


hwGetRemote  (PHP  3>=  3.0.3,  PHP  4  >=  4.0.0) 

Obtiene  un  documento  remoto 


int  hw_getremote  (int  conexion,  int  IDobjeto) 


Devuelve  un  documento  remoto.  Los  documentos  remotos  en  la  notacion  de  Hyperwave  son  los 
obtenidos  de  una  fuente  externa.  Los  documentos  remotos  tlpicos  son  paginas  web  externas  o  consultas  a 
bases  de  datos.  Para  poder  acceder  a  las  fuentes  externas  a  traves  de  documentos  remotos,  el  Hyperwave 
presenta  el  HGI  (Hyperwave  Gateway  Interface  -  Interfaz  de  Pasarela  de  Hyperwave)  que  es  similar  al 
CGI.  Actualmente,  solo  se  puede  acceder  a  servidores  ftp  y  http  y  a  algunas  bases  de  datos.  Llamar  a 
hw_GetRemote()  devuelve  el  documento  de  la  fuente  externa.  Si  desea  usar  esta  funcion  debe 
familiarizarse  con  los  HGI.  Deberfa  considerar  el  usar  PHP  en  lugar  del  Hyperwave  para  acceder  a 
fuentes  externas.  Anadir  soporte  de  bases  de  datos  a  traves  de  una  pasarela  Hyperwave  serfa  mas  diflcil 
que  hacerlo  en  PHP. 

Vea  tambien  hw_GetRemoteChildren(). 


hwGetRemoteChildren  (PHP  3>=  3.0.3,  PHP  4  >=  4.0.0) 


Obtiene  el  hijo  del  documento  remoto 


int  hw_getremotechildren  (int  conexion, 


string  registro  de 


objeto) 
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Devuelve  el  hijo  de  un  documento  remoto.  Los  hijos  de  documentos  remotos  son  en  si  mismos 
documentos  remotos.  Esto  tiene  sentido  cuando  se  afina  una  consulta  de  bases  de  datos  y  se  explica  en  la 
Grna  de  Programacion  de  Hyperwave.  Si  el  numero  de  hijos  es  1  la  funcion  devolvera  el  documento  en  si 
mismo  formateado  con  la  Interfaz  de  Pasarela  de  Hyperwave  (HGI).  Si  el  numero  de  hijos  es  mayor  de  1 
devolvera  una  tabla  de  registros  de  objeto,  con  cada  uno  posible  candidato  para  otra  llamada  a 
hw_GetRemoteChildren().  Dichos  registros  de  objeto  son  virtuales  y  no  existen  en  el  servidor 
Hyperwave,  y  por  lo  tanto  no  poseen  un  ID  de  objeto  valido.  La  apariencia  exacta  de  dicho  registro  de 
objeto  depende  del  HGI.  Si  desea  usar  esta  funcion  debera  estar  muy  familiarizado  con  los  HGI.  Tambien 
deberfa  considerar  el  uso  del  PHP  en  lugar  de  Hyperwave  para  acceder  a  fuentes  externas.  Anadir 
soporte  de  bases  de  datos  a  traves  de  una  pasarela  de  Hyperwave  resulta  mas  diffcil  que  hacerlo  en  PHP. 

Vea  tambien  hw_GetRemote(). 


hw_GetSrcByDestObj  (PHP  3>=  3.0.3,  PHP  4  >=  4.0.0) 


Devuelve  los  enlaces  que  apuntan  al  objeto 


array  hw_getsrcbydestob j  (int  conexion,  int  IDobjeto ) 


Devuelve  los  registros  de  objeto  de  todos  los  enlaces  que  apuntan  al  objeto  con  ID  IDobjeto.  El  objeto 
puede  ser  tanto  un  documento  como  un  enlace  de  tipo  destino. 

Vea  tambien  hw_GetAnchors(). 


hw_GetObject  (PHP  3>=  3.0.3,  PHP  4  >=  4.0.0) 


registro  de  objeto 


array  hw_getob ject  (int  conexion, 


[int | array] 


IDobjeto,  string  consulta) 


Devuelve  el  registro  de  objeto  para  el  objeto  cuyo  ID  es  IDobjeto  si  el  segundo  parametro  es  un 
entero.  Si  es  una  tabla  la  funcion  devolvera  una  tabla  de  registros  de  objeto.  En  tal  caso,  el  ultimo 
parametro,  que  es  una  cadena  de  consulta,  tambien  es  evaluado. 

La  cadena  de  consulta  tiene  la  sintaxis  siguiente: 

<expr>  ::=  "("  <expr>  ")"  I 

"!"  <expr>  I  /*  NO  */ 

<expr>  "II"  <expr>  I  /*  O  */ 

<expr>  "&&"  <expr>  I  /*  Y  */ 
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<atributo>  <operador>  <valor> 

<atributo>  ::=  /*  cualquier  atributo  (Tftulo,  Autor,  TipoDocumento  ...)  */ 

<operador>  ::=  "="  I  /*  igual  */ 

"<"  I  /*  menor  que  (comparacion  de  cadenas)  */ 

">"  I  /*  mayor  que  (comparacion  de  cadenas)  */ 

/*  expresion  regular  */ 

La  consulta  permite  seleccionar  elementos  de  la  lista  de  objetos  dada.  A1  contrario  de  otras  funciones  de 
busqueda,  esta  consulta  no  puede  utilizar  atributos  indizados.  El  numero  de  registros  de  objeto  devueltos 
depende  de  la  consulta  y  de  si  esta  permitido  el  acceso  al  objeto. 

Vea  tambien  hw_GetAndLock(),  hw_GetObjectByQuery(). 


hw  Get  And  Lock  (PHP  3>=  3.0.3,  PHP  4  >=  4.0.0) 

devuelve  registro  de  objeto  y  lo  bloquea 

string  hw_getandlock  (int  conexion,  int  IDobjeto) 

Devuelve  el  registro  de  objeto  para  el  objeto  con  ID  IDobjeto.  Tambien  bloqueara  el  objeto,  de  modo 
que  otros  usuarios  no  podran  acceder  al  mismo  hasta  que  sea  desbloqueado. 

Vea  tambien  hw_Unlock(),  hw_GetObject(). 


hwGetText  (PHP  3>=  3.0.3,  PHP  4  >=  4.0.0) 


obtiene  un  documento  de  texto 


int  hw_gettext  (int  conexion,  int  IDobjeto,  mixed  [ IDraiz/prefijo] ) 


Devuelve  el  documento  con  ID  de  objeto  IDobjeto.  Si  el  documento  tiene  enlaces  que  pueden  ser 
insertados,  seran  insertados  ahora.  El  parametro  opcional  IDraiz/prefijo  puede  ser  una  cadena  o 
un  entero.  Si  es  un  entero  determina  la  forma  en  que  los  enlaces  se  insertan  en  el  documento.  Por  defecto 
es  0  y  los  enlaces  se  crean  a  partir  del  nombre  del  objeto  de  destino  de  los  mismos.  Esto  es  util  para 
aplicaciones  web.  Si  un  enlace  apunta  a  un  objeto  con  nombre  ’pelicula_internet’  el  enlace  HTML  sera 
<A  HREF="/pelicula_internet">.  La  position  actual  del  objeto  de  destino  en  la  jerarqufa  de  documentos 
es  despreciada.  Tendra  que  ajustar  su  navegador  web  para  que  reescriba  dicho  URL  a,  por  ejemplo, 
7mi_script.php3/pelicula_internet’.  ’mi_script.php3’  debera  evaluar  $PATH_INFO  y  recuperar  el 
documento.  Todos  los  enlaces  tendran  el  prefijo  7mi_script.php3’.  Si  no  desea  este  efecto  puede  fijar  el 
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parametro  opcional  IDraiz/prefijo  al  prefijo  que  desee  en  su  lugar.  En  este  caso  debera  ser  una 
cadena. 

Si  el  IDraiz/prefijo  es  un  entero  distinto  de  0,  el  enlace  se  construye  con  todos  los  nombres  de 
objeto  comenzando  con  el  objeto  de  id  IDraiz/prefijo,  separado  por  una  barra  relativa  al  objeto 
actual.  Si  por  ejemplo  el  documento  anterior  ’pelicula_internet’  esta  situado  en  ’a-b-c-pelicula_internet’ 
donde  es  el  separador  entre  niveles  jerarquicos  en  el  servidor  Hyperwave  y  el  documento  fuente  esta 
situado  en  ’a-b-d-fuente’,  el  enlace  HTML  resultante  serfa:  <A  HREF="../c/pelicula_internet">.  Esto  es 
util  cuando  desea  bajarse  el  contenido  completo  del  servidor  al  disco  y  mapear  la  jerarqufa  de 
documentos  en  el  sistema  de  archivos. 

Esta  funcion  solo  trabajara  en  documentos  de  texto  puros.  No  se  abrira  una  conexion  de  datos  especial  y 
por  tanto  bloqueara  la  conexion  de  control  durante  la  transferencia. 

Vea  tambien  hw_PipeDocument(),  hw_FreeDocument(),  hw_DocumentBodyTag(), 
hw_DocumentSize() ,  h w_OutputDocument() . 


hw_GetObjectByQuery  (PHP  3>=  3.0.3,  PHP  4  >=  4.0.0) 

buscar  objeto 

array  hw_getob jectbyquery  (int  conexion,  string  consults,  int  max_resultados) 

Busca  objetos  en  todo  el  servidor  y  devuelve  una  tabla  de  id  de  objeto.  El  numero  maximo  de  resultados 
sera  max_resultados.  Si  max_resultados  vale  -1,  el  numero  maximo  de  resultados  es  ilimitado. 

La  consulta  funcionara  solo  con  atributos  indizados. 

Vea  tambien  hw_GetObjectByQueryObj(). 


hw_GetObjectByQueryObj  (php  3>=  3.0.3,  php  4  >=  4 .0 .0) 


buscar  objeto 


array  hw_getob jectbyqueryob j  (int  conexion,  string  consulta,  int 
max_re suit  ados) 


Busca  objetos  en  todo  el  servidor  y  devuelve  una  tabla  de  registros  de  objeto.  El  numero  maximo  de 
resultados  sera  max_resultados.  Si  max_resultados  vale  -1,  el  numero  maximo  de  resultados 
es  ilimitado. 

La  consulta  funcionara  solo  con  atributos  indizados. 

Vea  tambien  hw_GetObjectByQuery(). 


418 


Hyperwave 


hw_GetObjectByQueryColl  (PHP  3>=  3.0.3,  PHP  4  >=  4.0.0) 


buscar  objeto  en  coleccion 


array  hw_getob jectbyquerycoll  (int  conexion,  int  IDobjeto,  string  consults, 
int  max_resultados) 


Busca  objetos  en  la  coleccion  cuyo  ID  es  IDobjeto  y  devuelve  una  tabla  de  ID  de  objeto.  El  numero 
maximo  de  resultados  sera  max_resultados.  Si  max_resultados  vale  -1,  el  numero  maximo  de 
resultados  es  ilimitado. 

La  consulta  funcionara  solo  con  atributos  indizados. 

Vea  tambien  hw_GetObjectByQueryCollObj(). 


hw_GetObjectByQueryCollObj  (php  3>=  3.0.3,  php  4  >=  4 .0 .0 


buscar  objeto  en  coleccion 


array  hw_getob jectbyquerycollob j  (int  conexion,  int  IDobjeto,  string 
consulta,  int  max_resultados) 


Busca  objetos  en  la  coleccion  cuyo  ID  es  IDobjeto  y  devuelve  una  tabla  de  registros  de  objeto.  El 
numero  maximo  de  resultados  sera  max_resultados.  Si  max_resultados  vale  -1,  el  numero 
maximo  de  resultados  es  ilimitado. 

La  consulta  funcionara  solo  con  atributos  indizados. 

Vea  tambien  hw_GetObjectByQueryColl(). 


hwGetChildDocColl  (PHP  3>=  3.0.3,  PHP  4  >=  4.0.0) 

id  de  objeto  de  documentos  hijos  de  una  coleccion 

array  hw_getchilddoccoll  (int  conexion,  int  IDobjeto) 

Devuelve  una  tabla  de  id  de  objeto  para  los  documentos  hijos  de  una  coleccion. 
Vea  tambien  hw_GetChildren(),  hw_GetChildColl(). 
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hwGetChildDocCollObj  (PHP  3>=  3.0.3,  PHP  4  >=  4.0.0) 

registros  de  objeto  de  documentos  hijos  de  una  coleccion 

array  hw_getchilddoccollob j  (int  conexion,  int  IDobjeto ) 

Devuelve  una  tabla  de  registros  de  objeto  para  los  documentos  hijos  de  una  coleccion. 

Vea  tambien  hw_ChildrenObj(),  hw_GetChildCollObj(). 

hwGetAnchors  (PHP  3>=  3.0.3,  PHP  4  >=  4.0.0) 

id  de  objeto  de  los  enlaces  de  un  documento 

array  hw_getanchors  (int  conexion,  int  IDobjeto) 

Devuelve  una  tabla  de  id  de  objeto  con  los  enlaces  del  documento  cuyo  ID  es  IDobjeto. 


hwGetAnchorsObj  (PHP  3>=  3.0.3,  PHP  4  >=  4.0.0) 

registros  de  objeto  de  los  enlaces  de  un  documento 

array  hw_get anchor sob j  (int  conexion,  int  IDobjeto) 

Devuelve  una  tabla  de  registros  de  objeto  con  los  enlaces  del  documento  cuyo  ID  es  IDobjeto. 


hwMv  (PHP  3>=  3.0.3,  PHP  4  >=  4.0.0) 
mueve  objetos 

int  hw_mv  (int  conexion,  array  tabla  de  id  de  objeto,  int  id  origen,  int  id 
destino) 


Mueve  los  objetos  cuyas  id  se  especifican  en  el  segundo  parametro  desde  la  coleccion  con  id  i  d 
origen  hasta  la  coleccion  con  el  id  id  destino.  Si  el  id  de  destino  es  0,  los  objetos  seran  disociados 
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de  la  coleccion  origen.  Si  esta  fuese  la  ultima  instancia  del  objeto,  este  serfa  borrado.  Si  desea  borrar 
todas  las  instancias  de  una  vez,  utilice  hw_deleteobject(). 

El  valor  devuelto  es  el  numero  de  objetos  movidos. 

Vea  tambien  hw_cp(),  hw_deleteobject(). 


hwldentify  (PHP  3>=  3.0.3,  PHP  4  >=  4.0.0) 


identificarse  como  usuario 


int  hw_identify  (string  nombre,  string  clave) 


Le  identifica  como  el  usuario  nombre  y  clave.  La  identification  solo  es  valida  para  la  sesion  actual. 
No  pienso  que  esta  funcion  sea  necesaria  con  mucha  frecuancia.  En  muchos  casos  sera  mas  facil 
identificarse  al  abrir  la  conexion. 

Vea  tambien  hw_Connect(). 


hw  InCollections  (PHP  3>=  3.0.3,  PHP  4  >=  4.0.0) 


comprueba  si  los  id  de  objeto  estan  en  las  colecciones 


array  hw_incollections  (int  conexion,  array  tabla_id_objeto ,  array 
tabla_id_colecciones ,  int  colecciones_devueltas) 


Comprueba  si  el  conjunto  de  objetos  (documentos  o  colecciones)  especificado  por  el  parametro 
tabla_id_objeto  es  parte  de  las  colecciones  enumeradas  en  tabla_id_colecciones.  Cuando 
el  cuarto  parametro  colecciones_devueltas  es  0,  el  subconjunto  de  id  de  objeto  que  es  parte  de 
las  colecciones  (es  decir,  los  documentos  o  colecciones  hijos  de  una  o  mas  colecciones  de  id  de 
colecciones  o  de  sus  subcolecciones,  recursivamente)  es  devuelto  en  forma  de  tabla.  Cuando  el  cuarto 
parametro  es  1,  sin  embargo,  el  conjunto  de  colecciones  que  tienen  uno  o  mas  objetos  de  este 
subconjunto  como  hijos  es  devuelto  como  tabla.  Esta  opcion  permite  a  un  cliente,  p.  ej.,  remarcar  en  una 
visualization  grafica  la  parte  de  la  jerarqufa  de  colecciones  que  contiene  las  coincidencias  de  una 
consulta  previa. 


hw  Info 


(PHP  3>=  3.0.3,  PHP  4  >=  4.0.0) 


information  sobre  conexion 
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string  hw_info  (int  conexion) 


Devuelve  information  sobre  la  conexion  actual.  La  cadena  devuelta  tiene  el  siguiente  formato: 
<Cadenaservidor>,  <Anfitrion>,  <Puerto>,  <Usuario>,  <Puerto  del  Usuario>,  <Intercambio  de  bytes> 


hwInsColl  (PHP  3>=  3.0.3,  PHP  4  >=  4.0.0) 
insertar  coleccion 

int  hw_inscoll  (int  conexion,  int  IDobjeto,  array  tabla_objetos) 


Inserta  una  nueva  coleccion  con  los  atributos  de  la  tabla_objetos  en  la  coleccion  cuyo  ID  de  objeto 

es  IDobjeto. 


hw  InsDoc  (PHP  3>=  3.0.3,  PHP  4  >=  4.0.0) 


insertar  documento 


int  hw_insdoc  (int  conexion,  int  IDpadre,  string  registro_de_objeto,  string 
texto) 


Inserta  un  nuevo  documento  con  los  atributos  del  regl st ro_de_ob j et o  en  la  coleccion  cuyo  ID  de 
objeto  es  IDpadre.  Esta  funcion  inserta  tanto  un  registro  de  objeto  solo  como  un  registro  de  objeto  y  el 
texto  puro  en  ASCII  dado  en  texto  si  este  es  especificado.  si  desea  insertar  un  documento  general  de 
cualquier  tipo,  utilice  en  su  lugar  h  w_ i n s e rt d o c u  m e n t ' ) . 

Vea  tambien  hw_InsertDocument(),  hw_InsColl(). 


hw  InsertDocument  (php 3>=  3.0.3,  php 4 >=  4.0.0) 


subir  cualquier  objeto 


int  hw_insertdocument  (int  conexion,  int  id_padre ,  int  documento_hw) 


Sube  un  documento  a  la  coleccion  dada  por  id_padre.  El  documento  debe  ser  creado  antes  con  la 
funcion  hw_NewDocument().  Asegurese  que  el  registro  de  objeto  del  nuevo  documento  contenga  al 
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menos  los  atributos:  Type,  DocumentType,  Title  y  Name  (asf,  en  ingles).  Posiblemente  desee  fijar 
tambien  el  MimeType.  La  funcion  devuelve  la  id  de  objeto  del  nuevo  documento,  o  false. 

Vea  tambien  hw_PipeDocument(). 


hwJnsertObject  (PHP  3>=  3.0.3,  PHP  4  >=  4.0.0) 


inserta  un  registro  de  objeto 


int  hw_insertob ject  (int  conexidn, 


string  reg  de  objeto, 


string  parametro) 


Inserta  un  objeto  en  el  servidor.  Este  puede  consistir  en  cualquier  objeto  hyperwave  valido.  Vea  la 
documentation  sobre  el  HG-CSP  si  desea  information  detallada  sobre  cuales  tienen  que  ser  los 
parametros. 

Nota:  Si  se  desea  insertar  un  enlace,  el  atributo  Position  siempre  se  fijara  a  un  valor  comienzo/final  o  a 
’invisible’.  Las  posiciones  invisibles  se  necesitan  si  la  anotacion  no  tiene  enlace  correspondiente  en  el 
texto  anotado. 

Vea  tambien  hw_PipeDocument(),  hw_InsertDocument(),  hw_InsDoc(),  hw_InsColl(). 


hwmapid  (PHP  3>=  3.0.13,  PHP  4  >=  4.0.0) 

Mapea  in  id  global  a  un  id  virtual  local 

int  hw_mapid  (int  conexidn,  int  id  servidor ,  int  id  objeto ) 


Mapea  un  id  de  objeto  global  en  un  servidor  hyperwave,  incluso  con  aquellos  a  los  que  no  se  ha 
conectado  con  hw_connect  ),  sobre  un  id  virtual  de  objeto.  Este  id  virtual  se  puede  utilizar  como 
cualquier  otro  id  de  objeto,  p.  ej.  para  obtener  el  registro  de  objeto  por  medio  de  hw_getobject').  El  id  de 
servidor  es  la  primera  parte  del  id  global  de  objeto  (GOid)  de  aquel  que  es  realmene  el  numero  IP 
expresado  como  entero. 

Nota:  Para  usar  esta  funcion  debera  activar  el  indicador  F_DISTRIBUTED,  que  actualmenes  solo  se 
puede  fijar  en  tiempo  de  compilation  desde  hg_comm.c.  Por  defecto  esta  inactivo.  Lea  el  comentario  al 
principio  de  hg_comm.c 


hwModifyobject  (PHP  3>=  3.0.7,  PHP  4  >=  4.0.0) 


modifica  el  registro  de  objeto 


423 


Hyperwave 


int  hw_modif yob ject  (int  conexion,  int  objeto_a_cambiar,  array  eliminar , 
array  anadir,  int  modo ) 


Este  comando  permite  eliminar,  anadir,  o  modificar  atributos  individuates  de  un  registro  de  objeto.  El 
objeto  esta  especificado  por  el  ID  de  objeto  objeto_a_cambiar.  La  primera  tabla,  eliminar,  es  la 
lista  de  atributos  a  eliminar.  La  segunda  tabla,  anadir,  es  la  lista  de  atributos  a  anadir.  Para  modificar 
un  atributo,  hay  que  borrar  el  antiguo  y  anadir  uno  nuevo.  hw_modifyobject()  siempre  eliminara  los 
atributos  antes  de  anadir  los  nuevos  excepto  si  el  valor  del  atributo  a  eliminar  no  es  una  cadena  o  una 
tabla. 

El  ultimo  parametro  determina  si  la  modification  se  realiza  de  manera  recursiva.  1  quiere  decir  que  sea 
recursiva.  Si  alguno  de  los  objetos  no  se  puede  modificar,  sera  ignorado  sin  avisar.  Incluso  hw_error') 
podrfa  no  indicar  un  error  aunque  alguno  de  los  objetos  no  pueda  ser  modificado. 

Las  claves  de  ambas  tablas  son  los  nombres  de  los  atributos.  El  valor  de  cada  elemento  de  la  tabla  puede 
ser  una  tabla,  una  cadena  o  cualquier  otra  cosa.  Si  es  una  tabla,  cada  valor  de  atributo  se  construye  como 
la  clave  de  cada  elemento  mas  dos  puntos  y  el  valor  de  cada  elemento.  Si  es  una  cadena  se  toma  como 
valor  del  atributo.  Una  cadena  vacfa  producira  la  supresion  completa  del  atributo.  Si  el  valor  no  es  ni 
cadena  ni  tabla,  sino  otra  cosa,  p.  ej.  un  entero,  no  se  realizara  operacion  alguna  en  el  atributo.  Esto  es 
necesario  se  desea  anadir  un  atributo  completamente  nuevo,  no  solamente  un  nuevo  valor  para  un 
atributo  existente.  Si  la  tabla  eliminar  contuviera  una  cadena  vacfa  para  dicho  atributo,  este  se  intentarfa 
suprimir,  lo  que  fallarfa  porque  este  no  existe.  La  siguiente  adicion  de  un  nuevo  valor  para  dicho  atributo 
tambien  fallara.  Fijando  el  valor  para  dicho  atributo  p.  ej.  a  0  hara  que  ni  siquiera  se  intente  eliminar, 
pero  funcionara  la  adicion  del  mismo. 

Si  desea  cambiar  el  atributo  ’Nombre’  con  el  valor  actual  ’libros’  por  el  de  ’artfculos’  debera  crear  dos 
tablas  y  llamar  a  hw_modifyobject(). 

Ejemplo  1.  modificando  un  atributo 

//  $conexion  es  una  conexion  con  el  servidor  Hyperwave 
//  $idobj  es  la  ID  del  objeto  a  modificar 
$tablasupr  =  array ( "Nombre "  =>  "libros"); 

$tablaanad  =  array ( "Nombre "  =>  "articulos" )  ; 

$hw_modifyob ject ( $conexion,  $idobj,  $tablasupr,  $tablaanad) ; 


Para  borrar/anadir  un  par  nombre=valor  de/a  el  registro  de  objeto,  simplemente  pase  la  tabla 
eliminar/anadir  y  fije  el  ultimo/tercer  parametro  a  tabla  vacfa.  Si  el  atributo  es  el  primero  con  dicho 
nombre  que  se  anade,  fije  el  valor  del  atributo  en  la  tabla  eliminar  a  un  valor  entero. 


Ejemplo  2.  anadiendo  un  atributo  completamente  nuevo 

//  $conexion  es  una  conexion  con  el  servidor  Hyperwave 
//  $idobj  es  la  ID  del  objeto  a  modificar 
$tablasupr  =  array ( "Nombre "  =>  0); 

$tablaanad  =  array ( "Nombre "  =>  "articulos"); 

$hw_modifyob ject ( $conexion,  $idobj,  $tablasupr,  $tablaanad) ; 
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Nota:  Los  atributos  plurilingues,  p.  ej.  ’Tftulo',  se  pueden  modificar  de  dos  maneras.  O  bien 
proporcionando  los  valores  de  los  atributos  en  su  forma  nativa  ’lenguaje’:’tftulo’,  bien  proporcionando 
una  tabla  con  los  elementos  para  cada  lenguaje  segun  se  describe  mas  arriba.  El  ejemplo  anterior 
podria  quedar  entonces: 


Ejemplo  3.  modificando  el  atributo  Tftulo 

$tablasupr  =  array ( "Titulo"  =>  "es : Libros" ) ; 

$tablaanad  =  array ( "Titulo"  =>  "es :Articulos" ) ; 

$hw_modifyob ject ( $conexion,  $idobj,  $tablasupr,  $tablaanad) ; 


Ejemplo  4.  modificando  el  atributo  Tftulo 

$tablasupr  =  array ( "Titulo"  =>  arrayC'es"  =>  "Libros")); 

$tablaanad  =  array ( "Titulo"  =>  arrayC'es"  =>  "Articulos",  "ge"=>"Artikel" ) ) 
$hw_modifyob ject ( $conexion,  $idobj,  $tablasupr,  $tablaanad) ; 


Esto  elimina  el  tftulo  espanol  ’Libros’  y  anade  el  tftulo  espanol  ’Articulos’  y  el  tftulo  aleman  ’Artikel’. 


Ejemplo  5.  eliminando  atributos 

$tablasupr  =  array ( "Titulo"  =>  ""); 

$tablaanad  =  array  ( "Tnitulo"  =>  "es : Articulos ") ; 

$hw_modifyob ject ( $conexion,  $idobj,  $tablasupr,  $tablaanad) ; 


Nota:  Esto  eliminara  todos  los  atributos  con  el  nombre  ’Tftulo’  y  anadira  un  nuevo  atributo  ’Titulo'. 
Esto  es  util  cuando  se  desea  eliminar  atributos  de  forma  recursiva. 


Nota:  Si  necesita  eliminar  todos  los  atributos  con  un  cierto  nombre  tendra  que  pasar  una  cadena 
vacfa  como  el  valor  del  atributo. 


Nota:  Solo  los  atributos  ’Title’,  'Description'  y  ’Keyword’  (asf,  en  ingles)  manejaran  de  forma 
apropiada  el  prefijo  de  idioma.  Si  estos  atributos  no  llevaran  prefijo  de  idioma,  se  les  asignaria  el 
prefijo  ’xx’. 
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Nota:  El  atributo  ’Name’  es  bastante  especial.  En  algunos  casos  no  puede  ser  completamente 
eliminado.  Obtendra  un  mensaje  de  error  ’Change  of  base  attribute’  (’Cambio  de  atributo  base’,  no 
esta  muy  claro  cuando  ocurre).  Por  tanto,  tendra  siempre  que  anadir  un  nuevo  atributo  Name 
primero  y  luego  eliminar  el  anterior. 


Nota:  No  debe  rodear  esta  funcion  de  llamadas  a  hw_getandlock;)  ni  a  hw_unlock[). 
hw_modifyobject()  ya  lo  hace  internamente. 


Devuelve  true  si  no  hay  error  o  false  en  caso  contrario. 


hw  New  Document  (php 3>=  3.0.3,  php 4 >=  4.0.0) 


crear  nuevo  documento 


int  hw_new_document  (string  registro_de_objeto,  string  datos_documento ,  int 
tama_documento) 


Devuelve  un  nuevo  documento  Hyperwave  en  el  que  los  datos  del  documento  estan  fijados  a 
datos_documento  y  el  registro  de  objeto  a  registro_de_objeto.  La  longitud  de  los 
datos_documento  debe  pasarse  en  tama_documento.  Esta  funcion  no  inserta  el  documento  en  el 
servidor  Hyperwave. 

Vea  tambien  hw_FreeDocument(),  hw_DocumentSize(),  hw_DocumentBodyTag(), 
hw_OutputDocument(),  hw_InsertDocument() . 


hw_Objrec2Array  (PHP  3>=  3.0.3,  PHP  4  >=  4.0.0) 

convierte  atributos  de  registro  de  objeto  a  tabla  de  objetos 

array  hw_ob jrec2array  (string  registro_de_objeto ) 


Convierte  un  registro_de_objeto  en  una  tabla  de  objetos.  Las  claves  de  la  tabla  resultante  son  los 
nombres  de  los  atributos.  Los  atributos  multiples  como  ’Tftulo’  en  distintos  idiomas  forman  su  propia 
tabla.  Las  claves  de  esta  tabla  son  las  partes  a  la  izquierda  de  los  dos  puntos  del  valor  del  atributo. 
Actualmente,  solo  los  atributos  ’Title’,  ’Description’  y  ’Keyword’  (asi,  en  ingles)  son  correctamente 
tratados.  Otros  atributos  multiples  generan  una  tabla  indizada.  Actualmente,  solo  el  atributo  ’Group’  es 
tratado  correctamente. 
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Vea  tambien  hw_array2objrec '). 


hw_OutputDocument  <php  3>=  3.0.3) 

muestra  el  documento_hw 

int  hw_outputdocument  (int  documento_hw) 


Muestra  el  documento  sin  la  etiqueta  BODY. 


hw_pConnect  (PHP  3>=  3.0.3,  PHP  4  >=  4.0.0) 

hacer  una  conexion  de  base  de  datos  permanente 

int  hw  pconnect  (string  servidor ,  int  puerto,  string  usuario ,  string  clave) 


Devuelve  un  fndice  de  conexion  si  hay  exito,  o  false  si  la  conexion  no  puede  hacerse.  Abre  una 
conexion  permanente  a  un  servidor  Hyperwave.  Cada  uno  de  los  argumentos  debe  ser  una  cadena 
entrecomillada  excepto  el  numero  de  puerto.  El  argumento  usuario  y  la  clave  son  opcionales  y 
pueden  omitirse.  En  tal  caso  no  se  realizara  ninguna  identification  con  el  servidor.  Es  similar  a  la 
identification  anonima  del  usuario.  Esta  funcion  devuelve  un  fndice  de  conexion  que  se  necesita  para 
otras  funciones  de  Hyperwave.  Se  pueden  tener  varias  conexiones  permanentes  abiertas  a  la  vez. 

Vea  tambien  hw_Connect(). 


hwPipeDocument  (php 3>=  303  php 4 >=  4 .0 .0) 


recupera  cualquier  documento 


int  hw  pipedocument  (int  conexion,  int  IDobjeto) 


Devuelve  el  documento  Hyperwave  cuyo  ID  de  objeto  es  IDobjeto.  Si  el  documento  tiene  enlaces  que 
pueden  ser  insertados,  deberan  haberse  insertado  ya.  El  documento  sera  transferido  a  traves  de  una 
conexion  de  datos  especial  que  no  bloquea  la  conexion  de  control. 

Vea  tambien  hw_GetText()  para  saber  mas  sobre  insertion  de  enlaces,  hw_FreeDocument(), 
hw_DocumentSize(),  hw_DocumentBodyTag(),  hw_OutputDocument(). 
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hw  Root 


(PHP  3>=  3.0.3,  PHP  4  >=  4.0.0) 


ID  del  objeto  ralz 


int  hw_root  () 


Devuelve  la  ID  de  objeto  de  la  coleccion  hiper-ralz.  Actualmente  siempre  vale  0.  La  coleccion  hija  de  la 
hiper-ralz  es  la  coleccion  ralz  del  servidor  al  que  se  ha  conectado. 


hwUnlock  (PHP  3>=  3.0.3,  PHP  4  >=  4.0.0) 
desbloquea  objeto 

int  hw_unlock  (int  conexion,  int  IDobjeto) 

Desbloquea  un  documento  para  que  otros  usuarios  puedan  acceder  al  mismo  de  nuevo. 
Vea  tambien  hw_GetAndLock(). 


hwWho  (PHP  3>=  3.0.3,  PHP  4  >=  4.0.0) 

Lista  de  los  usuarios  actualmente  conectados 

int  hw_who  (int  conexion) 


Devuelve  una  tabla  de  los  usuarios  actualmente  conectados  al  servidor  Hyperwave.  Cada  elemento  de 
esta  tabla  contiene  en  si  mismo  los  elementos  ID,  nombre,  sistema,  onSinceDate 
(conectadoDesdeFecha),  onSinceTime  (conectadoDesdeHora),  TotalTime  (TiempoTotal)  y  self  (propio). 
’self’  es  1  si  esta  llnea  corresponde  al  usuario  que  realizo  la  peticion. 


hwUsername  (unknown) 

nombre  del  usuario  actualmente  conectado 

string  hw_getusername  (int  conexion) 
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Devuelve  el  nombre  de  usuario  de  la  conexion. 
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XXXIV.  Funciones  para  ICAP  -  Internet  Calendar 
Application  Protocol 

Para  hacer  funcionar  estas  funciones,  debera  compilar  el  PHP  con  — with-icap.  Eso  indicara  que  se 
precisa  la  instalacion  de  la  librerfa  ICAP.  Obtenga  la  ultima  version  en  http://icap.chek.com/,  compilela  e 
instalela. 
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icap_open  (PHP  4  >=  4.0.0) 


Abre  una  conexion  ICAP 


stream  icap_open  (string calendar io ,  stringusuario,  string clave, 
string opciones) 


Si  hay  exito  devuelve  un  stream  (flujo)  ICAP,  o  false  en  caso  de  error. 

icap_open()  abre  una  conexion  ICAP  con  el  servidor  de  calendario  especificado.  Si  se  especifica  el 
parametro  opcional  opciones,  tambien  este  es  pasado  a  dicho  buzon. 


icap_close  (unknown) 

Cierra  un  stream  ICAP 

int  icap_close  (int  stream_icap ,  int  banderas) 


Cierra  el  stream  ICAP  dado. 


icap_fetch_event  <php  4  >=  4  o  o> 

Obtiene  un  evento  del  stream  de  calendario/ 


ob jecticap_fetch_event  (stream stream_icap,  id id_evento,  options opciones) 


icap_fetch_event()  obtiene  el  evento  del  stream  de  calendario  especificado  por  el  parametro 

id_evento. 

Devuelve  un  objeto  de  evento  compuesto  por: 

•  int  id  -  ID  de  dicho  evento. 

•  int  public  -  true  si  el  evento  es  publico,  false  si  es  privado. 

•  string  category  -  Cadena  con  la  categorfa  del  evento. 

•  string  title  -  Cadena  de  tltulo  del  evento. 

•  string  description  -  Cadena  de  description  del  evento. 

•  int  alarm  -  Numero  de  minutos  antes  que  el  evento  envfe  una  alarma/recordatorio. 
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•  object  start  -  Objeto  que  contiene  una  entrada  datetime  (fecha/hora). 

•  object  end  -  Objeto  que  contiene  una  entrada  datetime. 

Todas  las  entradas  datetime  consisten  en  un  objeto  compuesto  por: 

•  int  year  -  ano 

•  int  month  -  mes 

•  int  mday  -  dfa  del  mes 

•  int  hour  -  hora 

•  int  min  -  minutos 

•  int  sec  -  segundos 


icap  Jist_events  (php  4  >=  4.0.0) 


Devuelve  una  lista  de  eventos  entre  dos  instantes  dados 


array  icap_list_events  (stream  stream_icap,  datetime  instante_inicio, 
datetime  instante_final) 


Devuelve  una  tabla  de  ID  de  evento  que  estan  entre  los  dos  instantes  dados. 

La  funcion  icap_list_events()  toma  un  instante  de  inicio  y  uno  de  final  para  un  stream  de  calendario.  Se 
devuelve  una  tabla  de  ID  de  evento  que  estan  entre  los  instantes  dados. 

Todas  las  entradas  datetime  consisten  en  un  objeto  compuesto  por: 

•  int  year  -  ano 

•  int  month  -  mes 

•  int  mday  -  dfa  del  mes 

•  int  hour  -  hora 

•  int  min  -  minutos 

•  int  sec  -  segundos 


icap_store_event  (PHP  4  >=  4.0.0) 


Almacena  un  evento  en  un  calendario  ICAP 
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icap_store_event()  Guarda  un  evento  en  un  calendario  ICAP.  Un  objeto  de  evento  consiste  en 

•  int  public  -  1  si  es  publico,  0  si  es  privado; 

•  string  category  -  Cadena  con  la  categorfa  del  evento. 

•  string  title  -  Cadena  de  tltulo  del  evento. 

•  string  description  -  Cadena  de  description  del  evento. 

•  int  alarm  -  Numero  de  minutos  antes  que  el  evento  envle  una  alarma/recordatorio. 

•  object  start  -  Objeto  que  contiene  una  entrada  datetime  (fecha/hora). 

•  object  end  -  Objeto  que  contiene  una  entrada  datetime. 

Todas  las  entradas  datetime  consisten  en  un  objeto  compuesto  por: 

•  int  year  -  ano 

•  int  month  -  mes 

•  int  mday  -  dla  del  mes 

•  int  hour  -  hora 

•  int  min  -  minutos 

•  int  sec  -  segundos 

Devuelve  true  en  caso  de  exito  y  false  en  caso  de  error. 


icap_delete_event  (php  4  >=  4.0.0 

Borra  un  evento  de  un  calendario  ICAP 

int  icap_delete_event  (int  id_evento ) 

icap_delete_event()  borra  el  evento  de  calendario  especificado  por  el  id_evento. 
Devuelve  true. 


ICAP 


icap_snooze  (PHP  4  >=  4.0.0) 

Apaga  la  alarma  de  un  evento 

int  icap_snooze  (int  id_evento) 

icap_snooze()  apaga  la  alarma  del  evento  de  calendario  especificado  por  el  id_evento. 
Returns  true. 


icap  Jist_alarms  (php  4  >=  4  o  0) 

Devuelve  una  lista  de  los  eventos  que  una  alarma  ha  disparado  en  el  instante  dado 

array  icap_list_alarms  (stream  stream_icap,  datetime  instante_alarma) 


Devuelve  una  tabla  de  identificadores  de  evento  para  los  que  una  alarma  debiera  apagarse  en  el  instante 
indie  ado. 

La  funcion  icap_list_alarms()  toma  una  estructura  datetime  para  un  stream  de  calendario.  Se  devuelve 
una  tabla  de  los  identificadores  de  evento  de  todas  las  alarmas  que  debieran  apagarse  en  el  instante 
indie  ado. 

Todas  las  entradas  datetime  consisten  en  un  objeto  compuesto  por: 

•  int  year  -  ano 

•  int  month  -  mes 

•  int  mday  -  dfa  del  mes 

•  int  hour  -  hora 

•  int  min  -  minutos 

•  int  sec  -  segundos 
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XXXV.  iconv  functions 


This  module  contains  an  interface  to  the  iconv  library  functions.  To  be  able  to  use  the  functions  debited 
in  this  module  you  must  compile  you  PHP  interpreter  using  the  — with-iconv  option.  In  order  to  do  so, 
you  must  have  iconv()  function  in  standard  C  library  or  libiconv  installed  on  your  system,  libiconv 
library  is  available  from  http://clisp.cons.org/~haible/packages-libiconv.html 
(http://clisp.cons.org/~haible/packages-libiconv.html). 

iconv  library  function  converts  hies  between  various  encoded  character  sets.  The  supported  character  sets 
depend  on  iconvQ  implementation  on  your  system.  Note  that  iconv()  function  in  some  system  is  not  work 
well  as  you  expect.  In  this  case,  you  should  install  libiconv  library. 


435 


iconv 


iconv  (PHP  4  >=  4.0.5) 

Convert  string  to  requested  character  encoding 

string  iconv  (string  in_charset ,  string  out_charset ,  string  str) 

It  converts  the  string  string  encoded  in  in_charset  to  the  string  encoded  in  out_charset.  It 
returns  the  converted  string  or  false,  if  it  fails. 

Ejemplo  1.  iconv()  example: 

echo  iconv (" ISO-885 9-1 ", "UTF-8 ", "This  is  test."); 


iconv_get_encoding  (php  4  >=  4  o  5) 

Get  current  setting  for  character  encoding  conversion 

array  iconv_get_encoding  ([string  type]) 

It  returns  the  current  settings  of  ob_iconv_handler()  as  array  or  false  in  failure. 

See  also:  iconv_set_encoding')  and  ob_iconv_handler'). 

iconv_set_encoding  (php4>=4.o.5) 

Set  current  setting  for  character  encoding  conversion 

array  iconv_set_encoding  (string  type,  string  charset) 

It  changes  the  value  of  type  to  charset  and  returns  true  in  success  or  false  in  failure. 
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Ejemplo  1.  iconv_set_encoding()  example: 

iconv_set_encoding ( " internal_encoding" ,  "UTF-8") ; 

iconv_set_encoding ( "output_encoding"  ,  "ISO-885  9-1") ; 


See  also:  iconv_get_encoding ))  and  ob_iconv_handlcr  'j. 

ob_iconv_handler  (php  4  >=  4.0.5) 

Convert  character  encoding  as  output  buffer  handler 

array  ob_iconv_handler  (string  contents ,  int  status) 

It  converts  the  string  encoded  in  internal_encoding  to  output_encoding. 

internal_encoding  and  output_encoding  should  be  defined  by  iconv_set_encodingO  or  in 
configuration  file. 

Ejemplo  1.  ob_iconv_handler()  example: 

ob_start ( "ob_iconv_handler " ) ;  //  start  output  buffering 

See  also:  iconv_get_encoding ))  and  iconv_set_encodingO- 
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XXXVI.  Funciones  de  Imageries 

Puede  usar  las  funciones  de  imagenes  de  PHP  para  obtener  el  tamano  de  imagenes  JPEG,  GIF  y  PNG,  y 
si  tiene  la  libreria  GD  (disponible  en  http://www.boutell.com/gd/)  ademas  sera  capaz  de  crear  y 
manipular  imagenes. 
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GetlmageSize  (PHP  3,  PHP  4  >=  4.0.0) 

Obtiene  el  tamano  de  una  imagen  GIF,  JPG  o  PNG 

array  getimagesize  (string  filename  [,  array  imageinfo ]) 


La  funcion  GetImageSize()  determinara  el  tamano  de  cualquier  fichero  de  imagen  GIF,  JPG  o  PNG  y 
devolvera  sus  dimensiones  junto  al  tipo  de  fichero  en  una  cadena  de  texto  que  pueda  ser  usada  en  una 
marca  HTML  IMG  normal. 

Devuelve  una  matriz  con  4  elementos.  El  indice  0  contiene  la  anchura  de  la  imagen  en  pixels.  El  indice  1 
contiene  la  altura.  El  indice  2  es  una  marca  indicando  el  tipo  de  imagen.  1  =  GIF,  2  =  JPG,  3  =  PNG.  El 
indice  3  es  una  cadena  de  texto  con  el  string  correcto  "height=xxx  width=xxx"  para  ser  usado 
directamente  en  una  marca  IMG. 

Ejemplo  1.  GetlmageSize 

<?php  $size  =  Get ImageSize ( " img/f lag . jpg" ) ;  ?> 

<IMG  SRC="img/ flag . jpg"  <?php  echo  $size[3];  ?>> 


El  parametro  opcional  imageinfo  permite  extraer  informacion  adicional  del  fichero  de  imagen. 
Actualmente  esto  devolvera  las  diferentes  marcas  APP  de  los  JPG  en  una  matriz  asociada.  Algunos 
programas  usan  estas  marcas  APP  para  incluir  informacion  textual  en  las  imagenes.  Uno  bastante  comun 
incluye  informacion  IPTC  http://www.iptc.org/  en  la  marca  APP13.  Puede  usar  la  funcion  iptcparse') 
para  convertir  la  marca  binaria  APP13  en  algo  leible. 

Ejemplo  2.  GetlmageSize  devolviendo  IPTC 

<?php 

$size  =  GetlmageSize ( "testimg . jpg" , &$info) ; 
if  (isset($info["APP13"] ) )  { 

$iptc  =  iptcparse ( $info [ "APP13 "]) ; 
var_dump ($iptc) ; 

} 

?> 


Nota:  Esta  funcion  no  requiere  la  libreria  de  imagenes  GD. 
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ImageArc  (PHP  3,  PHP  4  >=  4.0.0) 


Dibuja  una  elipse  parcial 


int  imagearc  (int  im,  int  cx,  int  cy,  int  w,  int  h,  int  s,  int  e,  int  col) 


ImageArc  dibuja  una  elipse  parcial  centrada  en  cx,  cy  (la  esquina  superior  izquierda  es  0,0)  en  la  imagen 
que  representa  im.  w  y  h  especifican  la  anchura  y  altura  respectivamente  mientras  que  los  puntos  de 
inicio  y  final  vienen  indicados  por  los  parametros  s  y  e  en  grados. 


ImageChar  (PHP  3,  PHP  4  >=4.0.0) 

Dibuja  un  caracter  horizontalmente 

int  imagechar  (int  im,  int  font,  int  x,  int  y,  string  c,  int  col) 


ImageChar  dibuja  el  primer  caracter  de  c  en  la  imagen  identificada  como  id  con  su  esquina  superior 
izquierda  en  x,  y  (arriba  izquierda  es  0,0)  con  el  color  col.  Si  la  fuente  es  1,  2,  3,  4  o  5  se  usa  una 
fuente  predefinida  (numeros  mayores  corresponden  con  tamanos  mayores). 

Vea  tambien  image  loadfontj). 


ImageCharllp  (PHP  3,  PHP  4  >=  4.0.0) 


Dibuja  un  caracter  vertical 


int  imagecharup  (int  im,  int  font,  int  x, 


int  y, 


string  c, 


int  col) 


ImageCharUp  dibuja  el  caracter  c  verticalmente  en  la  imagen  identificado  como  im  en  las  coordenadas  x, 
y  (arriba  izquierda  es  0,0)  con  el  color  col.  Si  la  fuente  es  1,  2,  3,  4  o  5  se  usa  una  fuente  predefinida. 

Vea  tambien  imageloadfont)). 


ImageColorAllocate  (PHP  3,  PHP  4  >=4.0.0) 


Reserva  un  color  para  una  imagen 
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int  imagecolorallocate  (int  im,  int  red,  int  green,  int  blue) 


ImageColorAllocate  devuelve  un  identificador  del  color  representado  por  la  mezcla  de  los  componentes 
RGB  dados.  El  parametro  im  es  el  resultado  de  la  funcion  imagecreate').  ImageColorAlocate  tiene  que 
ser  invocada  para  crear  cada  color  que  va  a  ser  usado  por  la  imagen  que  representa  im. 

$white  =  ImageColorAllocate ( $im,  255,255,255); 

$black  =  ImageColorAllocate ( $im,  0,0,0); 


ImageColorAt  (PHP  3,  PHP  4  >=  4.0.0) 

Obtiende  el  indice  del  color  de  un  pixel 

int  imagecolorat  (int  im,  int  x,  int  y) 


Devuelve  el  indice  del  color  del  pixel  especificado  en  la  posicion  de  la  imagen. 
Vea  tambien  imagecolorset  )  y  imagecolorsforindex '). 


ImageColorClosest  (PHP  3,  PHP  4  >=4.0.0) 

Obtiene  el  indice  del  color  mas  cercano  al  color  especificado 

int  imagecolorclosest  (int  im,  int  red,  int  green,  int  blue) 

Devuelve  el  indice  del  color  de  la  paleta  de  la  imagen  que  sea  mas  "cercano"  al  valor  RGB  especificado. 

La  "distancia"  entre  el  color  deseado  y  cada  color  de  la  paleta  es  calculada  como  si  los  valores  RGB 
representasen  puntos  en  un  espacio  tridimensional. 

Vea  tambien  imagecolorexactO- 


ImageColorExact  (PHP  3,  PHP  4  >=4.0.0) 


Devuelve  el  indice  del  color  especificado 


int  imagecolorexact  (int  im,  int  red, 


int  green,  int  blue ) 
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Devuelve  el  indice  del  color  especificado  de  la  paleta  de  la  imagen. 

Si  el  color  no  existe  en  la  paleta  de  la  imagen,  se  devuelve  el  valor  -1. 

Vea  tambien  imagecolorclosest)). 

ImageColorResolve  (PHP  3>=  3.0.2,  PHP  4  >=  4.0.0) 

Devuelve  el  mdice  del  color  especificado  o  su  posible  altemativa  mas  cercana 

int  imagecolorresolve  (int  im,  int  red,  int  green,  int  blue) 

Esta  funcion  garantiza  el  resultado  de  un  indice  de  color  para  un  color  solicitado,  ya  sea  el  color  exacto  o 
su  alternativa  mas  cercana. 

Vea  tambien  imagecolorclosest)). 

ImageColorSet  (PHP  3,  PHP  4  >=  4.0.0) 

Establece  el  color  para  el  indice  de  la  paleta  especificado 

bool  imagecolorset  (int  im,  int  index,  int  red,  int  green,  int  blue) 

Establece  el  indice  especificado  de  la  paleta  con  el  color  introduciod.  Esto  es  util  para  crear  efectos  de 
rellenado  en  imagenes  con  paletas  sin  la  sobrecarga  de  tener  que  realizar  el  rellenado. 

Vea  tambien  imagecolorat'). 

ImageColorsForlndex  (PHP  3,  PHP  4  >=  4.0.0) 

Obtiene  los  colores  de  un  indice 

array  imagecolorsforindex  (int  im,  int  index) 

Devuelve  una  matriz  asociativa  con  las  claves  red,  green  y  blue  que  contienen  los  valores  apropiados 
para  el  color  especificado  en  el  indice. 

Vea  tambien  imagecolorat  ))  y  imagecolorexact)). 
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ImageColorsTotal  (PHP  3,  PHP  4  >=  4.0.0) 

Encuentra  el  numero  de  colores  de  la  paleta  de  una  imagen 

int  imagecolorstotal  (int  im) 

Encuentra  el  numero  de  colores  de  la  paleta  de  una  imagen. 

Vea  tambien  imagecolorat')  y  imagecolorsforindex')- 

ImageColorTransparent  (PHP  3,  PHP  4  >=  4.0.0) 

Define  un  color  como  transparente 

int  imagecolortransparent  (int  im  [,  int  col]) 

ImageColorTransparent  establece  como  color  transparente  a  col  en  la  imagen  im.  im  es  el  identificador 
de  imagen  devuelto  por  imagecreate  )  y  col  es  el  identificador  de  color  devuelto  por  imagecolorallocate'). 

Se  devuelve  el  identificador  del  color  transparente  (o  el  actual,  si  no  se  especifica  ninguno). 


ImageCopyResized  (PHP  3,  PHP  4  >=  4.0.0) 


Copia  y  redimensiona  parte  de  una  imagen 


int  imagecopyresized  (int  dst_im,  int  src_im,  int  dstX,  int  dstY,  int  srcX, 
int  srcY ,  int  dstW ,  int  dstH ,  int  srcW,  int  srcH) 


ImageCopyResize  copia  una  portion  rectangular  de  una  imagen  hacia  otra  imagen.  dst_im  es  la 
imagen  de  destino,  src_im  es  el  identificador  de  la  imagen  origen.  Si  la  altura  y  anchura  de  las 
coordenadas  de  origen  y  destino  difieren  se  realizara  un  estrechamiento  o  un  estiramiento  apropiado  del 
fragmento  de  la  imagen.  Las  coordenadas  van  localizadas  sobre  la  esquina  superior  izquierda.  Esta 
funcion  se  puede  usar  para  copiar  regiones  dentro  de  la  misma  imagen  (si  dst_im  es  igual  que 
src_im )  pero  si  las  regiones  se  solapan  los  resultados  seran  impredecibles. 
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ImageCreate  (PHP3,  PHP  4  >=  4.0.0) 

Crea  una  nueva  imagen 

int  imagecreate  (int  x_size,  int  y_size) 

ImageCreate  devuelve  un  identificador  de  imagen  representando  una  imagen  en  bianco  de  tamano  x_size 
por  y_size. 


ImageCreateFromGif  (PHP  3,  PHP  4  >=  4.0.0) 

Crea  una  nueva  imagen  desde  un  fichero  o  una  URL 

int  imagecreatef romgif  (string  filename) 


imagecreatefromgifO  devuelve  un  identificador  de  imagen  representando  la  imagen  obtenida  del 
nombre  del  fichero  dado. 

imagecreatefromgifO  devuelve  una  cadena  vacia  si  hay  algun  fallo.  Ademas  muestra  un  mensaje  de 
error,  que  desafortunadamente  se  representa  como  un  link  roto  en  un  navegador.  Para  depurarlo 
facilmente  el  siguiente  ejemplo  producira  un  error  de  GIF: 

Ejemplo  1.  Ejemplo  de  control  de  un  error  durante  la  creacion  (cortesia  vic@zymsys.com  ) 


function  LoadGif (Simgname) 

{ 

$im  =  Oimagecreatef romgif ( $imgname) ;  /*  Attempt  to  open  */ 
if  ($im  ==  "")  {  /*  See  if  it  failed  */ 

$im  =  ImageCreate ( 150 , 30 ) ;  /*  Create  a  blank  image  */ 

$bgc  =  ImageColorAllocate ($im, 255, 255, 255) ; 

$tc  =  ImageColorAllocate ( $im, 0 , 0 , 0 ) ; 

ImageFilledRectangle ($im, 0,0, 150, 30, $bgc) ; 

ImageString ($im, 1, 5, 5, "Error  loading  $imgname" , $tc) ;  /*  Output  an  errmsg  */ 

} 

return  $im; 


Nota:  Desde  que  todo  el  soporte  a  GIFs  ha  sido  eliminado  en  la  libreria  GD  a  partir  de  la  version 
1 .6,  esta  funcion  no  esta  disponible  si  esta  usando  esa  version  de  la  libreria  GD. 
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ImageDashedLine  (php 3,  php 4 >=  4 .0 ,0) 

Dibuja  una  lfnea  discontinua 

int  imagedashedline  (int  im,  int  xl,  int  yl ,  int  x2,  int  y2,  int  col) 

ImageLine  dibuja  una  lfnea  discontinua  desde  xl,yl  hasta  x2,  y2  (arriba  izquierda  es  0.0)  en  la  imagen 
im  con  el  color  col. 

Vea  tambien  imageline''). 

ImageDestroy  (php 3,  php 4 >=  4.o.0) 

Destruye  una  imagen 

int  imagedestroy  (int  im) 


ImageDestroy  libera  la  memoria  asociada  a  la  imagen  im.  im  es  la  imagen  devuelta  por  la  funcion 
imagecreate'). 


ImageFill  (PHP  3,  PHP  4  >=4.0.0) 

Relleno 

int  imagefill  (int  im,  int  x,  int  y,  int  col) 


ImageFill  realiza  un  relleno  empezando  en  la  coordenada  x,y  (arriba  izquierda  es  0,0)  con  el  color  col  en 
la  imagen  im. 


ImageFilled Polygon  (php 3  PHP 4 >=  4 .0 .o> 

Dibuja  un  polfgono  relleno 

int  imagef illedpolygon  (int  im,  array  points,  int  num_points ,  int  col) 
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ImageFilledPolygon  crea  un  pollgono  relleno  en  la  imagen  im,  points  es  una  matriz  PHP  conteniendo  los 
vertices  del  poligono,  por  ejemplo.  points[0]  =  xO,  points[l]  =  yO,  points[2]  =  xl,  points[3]  =  yl,  etc. 
num_points  es  el  numero  total  de  vertices. 


ImageFilledRectangle  (php 3,  php 4 >=  4 .0 .0) 


dibuja  un  rectangulo  relleno 


int  imagef illedrectangle  (int  im,  int  xl,  int  yl,  int  x2,  int  y2,  int  col ) 


ImageFilledRectangle  crea  un  rectangulo  relleno  con  color  col  en  la  imagen  im  comenzando  con  las 
coordenadas  superiores  izquierdas  xl,  yl  y  finalizando  en  las  coordenadas  inferiores  derechas  x2,  yl.  0,0 
es  la  esquina  superior  izquierda  de  la  imagen. 


ImageFillToBorder  (php  3,  php  4  >=  4.o.o) 

Relleno  de  un  color  especifico 

int  imagef illtoborder  (int  im,  int  x,  int  y,  int  border,  int  col) 


ImageFillToBorder  realiza  un  relleno  hasta  el  color  del  borde  que  esta  definido  por  border.  El  punto  de 
inicio  para  el  relleno  es  x,y  (arriba  izquierda  es  0,0)  y  la  region  se  rellena  con  el  color  col. 


ImageFontHeight  (php  3  php 4 >=  4 o 0> 

Devuelve  la  altura  de  una  fuente 

int  imagefontheight  (int  font) 

Devuelve  la  altura  en  pixels  de  un  caracter  en  un  fuente  especffica. 
Vea  tambien  imagefontwidth  ')  y  imageloadfont'). 
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ImageFontWidth  (php  3,  php 4 >=  4 o o> 

Devuelve  la  anchura  de  una  fuente 

int  imagefontwidth  (int  font ) 

Devuelve  la  anchura  en  pixels  de  un  caracter  en  un  fuente  especffica. 

Vea  tambien  imagefontheight  ')  y  imageloadfont  '). 


ImageGif 


(PHP  3,  PHP  4  >=4.0.0) 


Envla  una  imagen  al  navegador  o  a  un  fichero 


int  imagegif  (int  im,  string  filename) 


imagegif()  crea  el  fichero  GIF  en  filename  a  partir  de  la  imagen  im.  El  parametro  im  es  el  resultado  de 
usar  la  funcion  imagecreate;). 

El  formato  de  la  imagen  sera  GIF87a  a  menos  que  la  imagen  se  halla  hecho  transparente  con 
imagecolortransparent '),  en  cuyo  caso  el  formato  de  la  imagen  sera  GIF89a. 

El  parametro  del  nombre  del  fuichero  es  opcional,  y  si  se  deja  en  bianco,  la  imagen  sera  mostrada 
directamente.  Enviando  un  tipo  de  imagen/gif  usando  la  funcion  header;),  puede  crear  un  script  PHP  que 
muestre  imagenes  GIF  directamente. 

Nota:  Desde  que  todo  el  soporte  a  GIFs  ha  sido  eliminado  en  la  libreria  GD  a  partir  de  la  version 
1 .6,  esta  funcion  no  esta  disponible  si  esta  usando  esa  version  de  la  libreria  GD. 


Imagelnterlace  <php 3,  php 4 >=  4.0.o) 

Activa  o  desactiva  el  entrelazado 

int  imageinterlace  (int  im  [,  int  interlace ]) 


Imagelnterlacef)  activa  o  desactiva  el  bit  de  entrelazado.  Si  interlace  es  1  la  imagen  im  sera  entrelazada, 
y  si  interlace  es  0  el  bit  de  entrelazado  se  desactiva. 
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Esta  funcion  devuelve  como  ha  cambiado  el  estado  del  bit  de  entralazado  de  la  imagen. 


ImageLine  (PHP  3,  PHP  4  >=  4.0.0) 


Dibuja  una  lfnea 


int  imageline  (int  im,  int  xl,  int  yl,  int  x2,  int  y2,  int  col) 


ImageLine  dibuja  una  lfnea  desde  xl,yl  hasta  x2,y2  (arriba  izquierda  es  0,0)  en  la  imagen  im  con  el 
color  col. 

Vea  tambien  imagecreate ')  y  imagecolorallocate')- 


ImageLoadFont  (PHP  3,  PHP  4  >=  4.0.0) 

Carga  una  fuente  nueva 

int  imageloadfont  (string  file) 


ImageLoadFont  carga  una  fuente  de  bitmaps  definida  por  el  usuario  y  devuelve  un  identificador  para  esa 
fuente  (que  siempre  es  mayor  de  5,  de  forma  que  no  pueda  entrar  en  conflicto  con  las  fuentes 
predefinidas).. 

El  formato  del  fichero  de  la  fuente  es  actualmente  binario  y  dependiente  de  la  arquitectura.  Esto  significa 
que  tiene  que  generar  los  ficheros  de  las  fuentes  en  el  mismo  tipo  de  CPU  que  la  que  tiene  la  maquina 
que  esta  ejecutando  PHP. 


Tabla  1.  Formato  del  fichero  de  fuentes 


Posicion  en  bytes 

tipo  de  datos  C 

Descripcion 

byte  0-3 

int 

numero  de  caracteres  en  la  fuente 

byte  4-7 

int 

valor  del  primer  caracter  de  la 
fuente  (normalmente  32  para  el 
espacio) 

byte  8-11 

int 

Anchura  en  pixels  de  cada  caracter 

byte  12-15 

int 

Altura  en  pixels  de  cada  caracter 
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Posicion  en  bytes 

tipo  de  datos  C 

Descripcion 

byte  16- 

char 

matriz  con  los  datos  del  caracter, 
un  byte  por  pixel  en  cada  caracter, 
haciendo  un  total  de  (numero 
caracteres*  altura*anchura)  bytes. 

Vea  tambien  ImageFontWidthO  y  ImageFontHeight(). 


ImagePolygon  (php 3,  php 4 >=  4 .0 ,0) 


Dibuja  un  polfgono 


int  imagepolygon  (int  im,  array  points,  int  num_points ,  int  col) 


ImagePolygon  crea  un  polfgono  en  la  imagen  id.  points  es  un  array  PHP  conteniendo  los  vertices  del 
polfgono.  de  la  siguiente  forma  points[0]  =  xO,  pointsl  =  yO,  points[2]  =  xl,  points[3]  =  yl,  etc. 
num_points  es  el  numero  total  de  vertices. 

Vea  tambien  imagecreate '). 


ImagePSBBox  (PHP  3>=  3.0.9,  PHP  4  >=  4.0.0) 

Devuelve  el  borde  que  rodea  un  rectangulo  de  texto  usando  fuentes  PostScript  Typel 

array  imagepsbbox  (string  text,  int  font,  int  size,  int  space,  int  width, 
float  angle ) 


size  representa  pixels. 

space  perimte  cambiar  el  valor  por  defecto  de  un  espacio  en  una  fuentes.  Este  valor  es  anadido  al  valor 
normal  y  puede  ser  negativo. 

tightness  permite  controlar  la  cantidad  de  espacio  en  bianco  entre  caracteres.  Este  valor  se  anade  a  la 
anchura  normal  del  caracter  y  puede  ser  negativo. 

angle  viene  dado  en  grados. 

Los  parametros  space  y  tightness  vienen  expresados  en  unidades  de  espacio  de  caracteres,  donde 
una  unidad  es  1/1000  el  borde  de  una  M. 

Los  parametros  space,  tightness  y  angle  son  opcionales. 
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El  borde  es  calculado  usando  la  information  disponible  de  las  metricas  del  caracter,  y 
desafortunadamente  tiende  a  diferir  ligeramente  de  los  resultados  obtenidos  de  digitalizar  el  texto.  Si  el 
angulo  es  de  0  grados,  puede  esperar  que  el  texto  necesite  un  pixel  mas  en  cada  direction. 

Esta  funcion  devuelve  un  array  conteniuendo  los  siguientes  elementos: 


0 

coordenada  x  inferior  izquierda 

1 

coordenada  y  inferior  izquierda 

2 

coordenada  x  superior  derecha 

3 

coordenada  y  superior  derecha 

Vea  tambien  imagepstextO- 


ImagePSEncodeFont  (PHP  3>=  3.0.9,  PHP  4  >=  4.0.0) 

Cambia  el  vector  de  codificacion  de  caracteres  de  una  fuente 


int  imagepsencodefont  (string  encoding file) 


Carga  un  vector  de  codificacion  de  caracteres  desde  un  archivo  y  cambia  el  vector  de  codificacion  de  las 
fuentes  a  el.  Loads  a  character  encoding  vector  from  from  a  file  and  changes  the  fonts  encoding  vector  to 
it.  En  las  fuentes  PostScript  normalmente  faltan  muchos  caracteres  por  encima  de  127,  seguramente 
quiera  cambiar  esto  si  emplea  u  idioma  distinto  del  ingles. El  formato  exacto  de  este  archivo  esta  descrito 
en  la  documentation  de  Tllibs.  Tllib  viene  con  dos  archivos  listos  para  usar,  IsoLatinl.enc  y 
IsoLatin2.enc. 

Si  se  encuentra  usando  esta  funcion  todo  el  tiempo,  una  forma  mucho  mejor  de  definir  la  codificacion  es 
establecer  ps.default_encoding  en  el  archivo  de  configuration  para  que  apunte  al  archivo  de  codificacion 
correcto  y  todas  las  fuentes  que  cargue  tendran  de  forma  automatica  la  codificacion  correcta. 


ImagePSFreeFont  (PHP  3>=  3.0.9,  PHP  4  >=  4.0.0) 


Libera  la  memoria  usada  por  un  fuente  PostScript  Type  1 


void  imagepsf reef ont  (int  fontindex) 


Vea  tambien  imagepsloadfont  ). 
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ImagePSLoadFont  (PHP  3>=  3.0.9,  PHP  4  >=  4.0.0) 

Carga  una  fuente  PostScript  Type  1  desde  un  fichero 

int  imagepsloadfont  (string  filename) 


En  el  caso  de  que  todo  vaya  bien,  tiene  que  devolver  un  fndice  de  fuente  correcto  que  puede  ser  usado 
para  futuras  operaciones.  En  caso  contrario  la  funcion  devuelve  false  e  imprime  un  mensaje 
describiendo  donde  ha  fallado 

Vea  tambien  imagepsfrcefont 


ImagePSText  (PHP  3>=  3.0.9,  PHP  4  >=  4.0.0) 


Para  dibujar  una  cadena  de  texto  sobre  una  imagen  usando  fuentes  PostScript  Typel 


array  imagepstext  (int  image,  string  text,  int 
foreground,  int  background,  int  x,  int  y,  int 
[angle],  int  [antialias_steps ] ) 


font,  int  size,  int 
[space],  int  [tightness], 


float 


size  viene  expresado  en  pixels. 

foreground  es  el  color  en  el  cual  el  texto  sera  pintado,  background  es  el  color  en  el  que  el  texto 
tratara  de  resaltar  con  antialiaing.  Los  pixels  con  el  color  background  no  se  pintan,  de  forma  que  la 
imagen  de  fondo  no  necesita  ser  de  un  color  solido. 

Las  coordenadas  dadas  por  x,  y  definiran  el  origen  (o  punto  de  referenda)  del  primer  caracter  (la 
esquina  superior  izquierda  del  caracter).  Esto  es  diferente  de  la  funcion  ImageStringO,  donde  x,  y 
definen  la  esquina  superiro  derecha  del  primer  caracter.  Consulte  la  documentation  de  PostScript  sobre 
fuentes  y  su  sistema  de  medidas  si  tiene  algun  problema  entendiendo  como  funcion. 

spa  ce  permite  cambiar  el  valor  por  defecto  de  un  espacio  en  la  fuente.  Esta  cantidad  es  sumada  al  valor 
normal  y  puede  ser  negativa. 

tightness  permite  controlar  la  cantidad  de  espacio  en  bianco  entre  caracteres.  Esta  cantidad  es 
sumada  al  valor  normal  y  puede  ser  negativa. 

angle  viene  en  grados. 

antialias_steps  permite  controlar  el  numero  de  colores  usados  para  el  antialising  del  texto.  Los 
valores  permitidos  son  4  y  16.  El  valor  superior  esta  recomendado  para  textos  con  tamanos  inferiores  a 
20,  donde  el  efecto  en  la  calidad  del  texto  es  bastante  visible.  Con  tamanos  superiores  use  4.  Hace  un 
menor  uso  de  calculo. 

Parameters  space  y  tightness  estan  expresados  en  unidades  de  espacio  de  caracteres,  donde  1 
unidad  es  1/1000  de  una  M  mayuscula. 
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0 

coordenada  x  inferior  izquierda 

1 

coordenada  y  inferior  izquierda 

2 

coordenada  x  superior  derecha 

3 

coordenada  y  superior  derecha 

Vea  tambien  imagepsbbox '). 


ImageRectangle  (php 3  php 4 >=  4 .0 ,0) 

Dibuja  un  rectangulo 

int  imagerectangle  (int  im,  int  xl,  int  yl,  int  x2,  int  y2,  int  col) 


ImageRectangle  crea  un  rectangulo  de  color  col  en  la  imagen  im  comenzando  en  la  coordenada  superior 
izquierda  xl,yl  y  finalizando  en  la  coordenada  inferior  derecha  x2,y2.  0,0  es  la  esquina  superior 
izquierda  de  la  imagen. 


ImageSetPixel  (PHP  3,  PHP  4  >=4.0.0) 

Dibuja  un  pixel 

int  imagesetpixel  (int  im,  int  x,  int  y,  int  col) 

ImageSetPixel  dibuja  un  pixel  x,y  (arriba  izquierda  0,0)  en  la  imagen  im  con  color  col. 

Vea  tambien  imagecreate ))  y  imagecolorallocateO- 

ImageString  (PHP  3,  PHP  4  >=4.0.0) 

Dibuja  una  cadena  de  texto  horizintalmente 

int  imagestring  (int  im,  int  font,  int  x,  int  y,  string  s,  int  col) 
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ImageString  dibuja  la  cadena  s  en  la  imagen  identificada  por  im  en  las  coordenadas  x,y  (arriba  izquierda 
es  0,0)  en  el  color  col.  Si  la  fuente  es  1,  2,  3,  4  o  5,  se  emplea  una  fuente  interna. 

Vea  tambien  imageloadfont)). 


ImageStringllp  (PHP  3,  PHP  4  >=  4.0.0) 

Dibuja  una  cadena  de  texto  verticalmente 

int  imagestringup  (int  im,  int  font,  int  x,  int  y,  string  s,  int  col) 


ImageStringUp  dibuja  la  cadena  s  verticalmente  en  la  imagen  identificada  por  im  en  las  coordenadas  x,y 
(arriba  izquierda  es  0,0)  en  el  color  col.  Si  la  fuente  es  1,  2,  3,  4  o  5,  se  usa  una  fuente  interna. 

Vea  tambien  imageloadfont  ). 


ImageSX  (PHP  3,  PHP  4  >=4.0.0) 

Obtiene  la  anchura  de  la  imagen 

int  imagesx  (int  im) 

ImageSX  devuelva  la  anchura  de  la  imagen  identificado  por  im. 
Vea  tambien  imagecreate^)  y  imagesy)). 


ImageSY  (PHP  3,  PHP  4  >=4.0.0) 

Obtiene  la  altura  de  la  imagen 

int  imagesy  (int  im) 

ImageSY  devuelve  la  altura  de  la  imagen  identificada  por  im. 
Vea  tambien  imagecreate^)  y  imagesx)). 
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ImageTTFBBox  (PHP  3>=  3.0.1 ,  PHP  4  >=  4.0.0) 

Devuelve  un  caja  que  rodea  al  texto  usando  fuentes  TypeType 

array  ImageTTFBBox  (int  size,  int  angle,  string  font  file,  string  text) 


Esta  funcion  calcula  y  devuelve  un  rectangulo  en  pixels  que  encierra  un  texto  con  TrueType. 


text 


La  cadena  que  ha  de  ser  medida. 


size 


El  tamano  de  la  fuente. 


font  file 

El  nombre  del  archivo  de  fuente  TrueType.  (Puede  ser  tambien  una  URL.) 


angle 

Angulo  en  grados  en  el  text  que  va  a  ser  medido. 

ImageTTFBBox()  devuelve  una  matriz  con  8  elementos  representando  cuatro  puntos  que  hacen  una  caja 
rodeando  al  texto: 


0 

esquina  inferior  izquierda,  posicion  X 

1 

esquina  inferior  izquierda,  posicion  Y 

2 

esquina  inferior  derecha,  posicion  X 

3 

esquina  inferior  derecha,  posicion  Y 

4 

esquina  superior  derecha,  posicion  X 

5 

esquina  superior  derecha,  posicion  Y 

6 

esquina  superior  izquierda,  posicion  X 

7 

esquina  superior  izquierda,  posicion  Y 

Los  puntos  son  relativos  a  text  a  pesar  del  angulo,  de  forma  que  "superior  izquierda"  significa  la  esquina 
superior  izquierda  viendo  el  texto  horizontalmente. 

Esta  funcion  requiere  tanto  la  libreria  GD  como  la  libreria  Freetype. 

Vea  tambien  ImageTTFText(). 


ImageTTFText  (PHP  3,  PHP  4  >=4.0.0) 


Escribe  texto  en  la  imagen  usando  fuentes  TrueType 
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ImageTTFText  escribe  la  cadenatext  en  la  imagen  identificada  por  im,  comenzando  en  las 
coordenadas  x,  y  (arriba  izquierda  es  0,0),  con  un  angulo  de  angle  en  el  color  col,  usando  el  ficheor 
de  fuente  TrueType  identificado  por  font  file. 

Las  coordenadas  dadas  por  x,y  definiran  el  punto  base  del  primer  caracter.  (la  esquina  inferior  izquierda 
del  caracter).  Esto  es  diferente  de  la  funcion  ImageStringO,  donde  x,y  definen  la  esquina  superior 
derecha  del  primer  caracter. 

El  angle  viene  dado  en  grados,  donde  0  grados  representa  el  texto  de  izquierda  a  derecha  (direccion  las 
3  en  punto),  y  valores  superiores  representan  una  rotacion  en  el  sentido  de  las  agujas  de  un  reloj.  (ej.  un 
valor  de  90  representarla  un  texto  que  fuese  de  abajo  hacia  arriba). 

font  file  es  la  mta  hacia  la  fuente  TrueType  que  desee  usar. 

text  es  la  cadena  de  texto  que  puede  incluir  secuencias  de  caracteres  UTF-8  (de  la  forma:  &123; )  para 
acceder  a  caracteres  de  la  fuente  mas  alia  de  los  primeros  255. 

col  es  el  fndice  de  color.  El  uso  de  un  fndice  de  color  negativo  tiene  el  efecto  de  desactivar  el 
antialiasing. 

ImageTTFTextO  devuelve  una  matriz  con  8  elementos  representando  cuatro  puntos  que  hace  una  caja 
que  cubre  el  texto. El  orden  de  los  puntos  en  arriba  izquierda,  arriba  derecha,  abajo  derecha,  abajo 
izquierda.  Los  puntos  son  relativos  al  texto  a  pesar  del  angulo,  por  lo  que  "arriba  izquierda"  significa  en 
la  esquina  superior  izquierda  cuando  ve  el  texto  horizontalmente. 

Este  script  de  ejemplo  producira  un  GIF  negro  de  400x30  pixels,  con  las  palabras  "Testing..."  en  bianco 
con  la  fuente  Arial. 


Ejemplo  1.  ImageTTFText 


<?php 

Header ( "Content-type :  image/gif" 
$im  =  imagecreate  (400, 30) ; 

$black  =  ImageColorAllocate ($im, 
$white  =  ImageColorAllocate ( $im, 
ImageTTFText ($im,  20,  0,  10,  20, 
ImageGif ( $im) ; 

ImageDestroy ($im) ; 

?> 


0,0,0)  ; 

255, 255, 255) ; 

$white,  " /path/ arial .ttf". 


"Testing...  Omega:  &#937 


Esta  funcion  requiere  la  libreria  GD  y  la  libreria  FreeType  (http://www.freetype.org/). 
Vea  tambien  ImageTTFBBox(). 
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Para  hacer  funcionar  estas  funciones,  debe  compilar  PHP  con  — with-imap.  Esto  requiere  que  la 
libreria  c-client  este  instalada.  Obtenga  la  ultima  version  de  ftp://ftp.cac.washington.edu/imap/  y 
compflela.  Luego  copie  c-client/c-client  .a  al  directorio  /usr/local/lib  o  a  cualquier  otro 
directorio  de  su  LINK  path  y  copie  c-client /rf  c822  . h,  mail .  h  y  linkage  .  h  al  directorio 
/usr/local/include  o  a  cualquier  otro  de  su  INCLUDE  path. 

Decir  que  estas  funciones  no  estan  limitadas  al  protocolo  IMAP,  a  pesar  de  sus  nombres.  La  libreria 
subyacente  c-client  tambien  soporta  NNTP,  POP3  y  metodos  de  acceso  local  a  buzones  de  correo.  Vea 
imap_open')  para  una  mayor  informacion. 


456 


IMAP 


imap_append  (PHP  3,  PHP  4  >=  4.0.0) 

Agrega  una  cadena  de  mensaje  al  buzon  especificado 

int  imap_append  (int  imap_stream,  string  mbox,  string  message ,  string flags) 

Devuelve  true  si  no  hay  error  y  false  en  caso  contrario. 

imap_append()  agrega  una  cadena  de  mensaje  al  buzon  especificado  mbox.  Si  se  especifica  el 
parametro  flags,  escribe  las  opciones  o  condiciones  establecidas  en  el  parametro  flags  al  buzon. 

Cuando  conecte  con  el  servidor  Cyrus  IMAP,  debe  usar  "\r\n"  como  finalizador  de  linea  en  vez  de  "\n"  o 
la  operacion  fallara. 

imap_base64  (PHP  3,  PHP  4  >=4.0.0) 

Decodifica  texto  codificado  en  BASE64 

string  imap_base64  (string  text) 

imap_base64()  decodifica  texto  codificado  en  BASE-64.  El  mensaje  decodificado  es  devuelto  como  una 
cadena. 


imap_body  (PHP  3,  PHP  4  >=4.0.0) 


Lee  el  cuerpo  del  mensaje 


string  imap_body  (int  imap_stream,  int  msg_number ,  int  flags) 


imap_body()  devuelve  el  cuerpo  del  mensaje,  numerado  msg_number  del  buzon  actual.  Los  flags 
opcionales  son  una  mascara  de  bit  con  una  o  mas  de  las  siguientes: 

•  FT_UID  -  El  msgno  es  un  UID 

•  FT_PEEK  -  No  activar  \Seen  flag  si  no  esta  ya  activa 

•  FT_INTERNAL  -  La  cadena  devuelta  esta  en  formato  interno,  no  canoniza  a  CRLF. 
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imap_check  (PHP  3,  PHP  4  >=  4.0.0) 

Comprueba  el  estado  del  buzon  actual 

object  imap_check  (int  imap_stream) 


Devuelve  informacion  acerca  del  buzon  actual.  Devuelve  false  si  falla. 

La  funcion  imap_check()  comprueba  el  estado  del  buzon  actual  en  el  servidor  y  devuelve  la  informacion 
en  un  objeto  con  las  siguientes  propiedades. 


Date  :  fecha  del  mensaje 

Driver  :  controlador 

Mailbox  :  nombre  del  buzon 

Nmsgs  :  numero  de  mensajes 

Recent :  numero  de  mensajes  recientes 


imap_close  (PHP  3,  PHP  4  >=  4.0.0) 

Cierra  una  sesion  IMAP 

int  imap_close  (int  imap_stream,  int  flags) 

Cierra  una  sesion  imap.  Toma  un  parametro  flag  opcional,  CL_EXPUNGE,  el  cual  purgara  el  buzon  de 
forma  trasparente  antes  de  cerrarla. 

imap_createmailbox  (php  3,  PHP  4  >=  4  o  o> 

Crea  un  buzon  nuevo 

int  imap_createmailbox  (int  imap_stream,  string  mbox) 

imap_createmailbox()  crea  un  buzon  nuevo  especificado  por  mbox  (ver  imap_open ')  para  el  formato 
del  parametro  mbox). 

Devuelve  true  si  no  hay  error  y  false  en  caso  contrario. 
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Ver  Tambien  imap_renamemailboxO  y  imap_deletemailboxO- 

imap_delete  (PHP3,  PHP  4  >=  4.0.0) 

Marca  un  mensaje  para  ser  borrado  en  el  buzon  actual 

int  imap_delete  (int  imap_stream,  int  msg_number) 

Devuelve  true. 

La  funcion  imap_delete()  marca  el  mensaje  referenciado  por  msg_number  para  su  eliminacion.  El 
borrado  ffsico  de  los  mensajes  es  realizado  por  imap_expunge"). 

imap_deletemailbox  (php  3,  PHP  4  >=  4.0.0 

Elimina  un  buzon 

int  imap_deletemailbox  (int  imap_stream,  string  mbox) 

imap_deletemailbox()  elimina  el  buzon  especificado  (ver  imapopen  )  para  el  formato  del  mbox). 
Devuelve  true  si  no  hay  error  y  false  en  caso  contrario. 

Ver  Tambien  i m a p_cre at e m ailbox  Q  y  imap_reanmemailbox(). 

imap_expunge  (PHP  3,  PHP  4  >=4.0.0) 

Elimina  todos  los  mensajes  marcados  como  borrados 

int  imap_expunge  (int  imap_stream) 

imap_expunge()  elimina  todos  los  mensajes  marcados  por  la  funcion  imap_dclete  ). 

Devuleve  true. 
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imap_f  etch  body  (php  3,  php  4  >=  4.o.0) 


Localiza  una  seccion  particular  en  el  cuerpo  del  mensaje 


string  imap_fetchbody  (int  imap_stream,  int  msg_number ,  string  part_number, 
flags  flags) 


Esta  funcion  busca  una  seccion  particular  en  el  cuerpo  de  los  mensajes  especificados,  como  una  cadena 
de  texto  y  devuleve  esa  cadena.  La  especificacion  de  la  seccion  es  una  cadena  de  enteros  delimitados  por 
comasjos  cuales  indexan  las  partes  del  cuerpo  como  indica  la  especificacion  IMAP4.  Partes  del  cuerpo 
no  son  decodificadas  por  esta  funcion. 

Las  opciones  para  imap_fetchbody  ()  son  una  mascara  de  bit  con  una  o  mas  de  las  siguientes 

•  LT_UID  -  El  msgono  es  un  UID 

•  LT_PEEK  -  No  activar  \Seen  flag  si  no  esta  ya  activa 

•  LT_INTERNAL  -  La  cadena  devuelta  esta  en  formato  "interno",  sin  ningun  intento  por  canonizar 
CRLL 


imap_fetchstructure  (php 3  php 4 >=  4 o 0) 

Lee  la  estructuta  de  un  mensaje  concreto 

object  imap_fetchstructure  (int  imap_stream,  int  msg_number  [,  int  flags]) 


Esta  funcion  busca  toda  la  informacion  estructurada  en  el  mensaje  especificado.  El  parametro  opcional 
flags  solo  tiene  una  opcion,  FT_UID,  la  cual  indica  a  la  funcion  que  trate  el  argumento 
msg_number  como  un  UID.  El  objeto  devuelto  incluye  el  sobre,  la  fecha  interna,  el  tamatto,  flags  y  la 
estructura  del  cuerpo  con  un  objeto  similar  por  cada  mime  adjunto  al  mensaje.  La  estructura  de  los 
objetos  devueltos  es  como  sigue: 


Tabla  1.  Objetos  Devueltos  para  imap_fetchstructure() 


type 

Tipo  primario  del  cuerpo 

encoding 

Body  transfer  encoding 

ifsubtype 

true  si  hay  una  cadena  de  subtipo 

subtype 

MIME  subtype 

ifDescripcion 

true  si  hay  una  cadena  de  Description 
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Description 

Conenido  de  la  cadena  de  Description 

ifid 

true  si  hay  una  cadena  de  identificacion 

id 

Cadena  de  Identificacion 

lines 

Numero  de  lineas 

bytes 

Numero  de  bytes 

^disposition 

true  si  hay  una  cadena  de  configuracion 

disposition 

Cadena  de  configuracion 

ifdparameters 

true  si  el  array  dparameters  existe 

dparameters  a 

Array  de  parametro  de  configuracion 

ifparameters 

true  si  el  array  de  parametros  existe 

parameters  b 

MIME  parameters  array 

parts  c 

Array  de  objetos  describiendo  cada  parte  del 
mensaje 

Notas:  a.  dparameters  es  un  array  de  objetos  donde  cada  objeto  tiene  un  "atributo"  y  una  propiedad  "valor",  b.  parameter 


Tabla  2.  Tipo  primario  del  cuerpo 


0 

texto 

1 

multiparte 

2 

mensaje 

3 

aplicacion 

4 

audio 

5 

imagen 

6 

video 

7 

otro 

Tabla  3.  Codificacion  para  tranferencia 


0 

7BIT 

1 

8BIT 

2 

BINARY 

3 

BASE64 

4 

QUOTED-PRINTABLE 

5 

OTRO 
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imap_header  (PHP3,  PHP  4  >=  4.0.0) 


Lee  la  cabecera  del  mensaje 


object  imap_header  (int  imap_stream, 
subjectlength  [,  string  defaulthost ] 


int  msg_number 
]  ) 


int  fromlength  [,  int 


Esta  funcion  devuelve  un  objeto  con  varios  elementos  de  la  cabecera. 


remail,  date.  Date,  subject.  Subject,  in_reply_to,  message_id, 
newsgroups,  followup_to,  references 

message  flags: 

Recent  -  ’R’  si  es  reciente  y  ha  sido  leido, 

’N’  si  es  reciente  y  no  ha  sido  leido, 

’  ’  si  no  es  reciente 

Unseen  -  ’U’  si  no  ha  sido  leido  Y  no  es  reciente, 

’  ’  si  ha  sido  leido  O  no  y  es  reciente 
Answered  -’A’  si  ha  sido  contestado, 

’  ’  si  no  ha  sido  contestado 
Deleted  -  ’D’  si  ha  sido  borrado, 

’  ’  si  no  ha  sido  borrado 
Draft-  ’X’ if  draft, 

’  ’  if  not  draft 

Flagged  -  ’F’  si  esta  if  flagged, 

’  ’  if  not  flagged 

OBSERVE  que  el  comportamiento  Recent/Unseen  es  un  poco  extratto.  Si  quiere  conocer 
si  un  mensaje  es  Unseen,  debe  comprobarlo  asi 


Unseen  ==  ’U’  II  Recent  ==  ’N’ 


toaddress  (la  linea  to:  al  completo,  hasta  1024  caracteres) 

to[]  (devuelve  un  array  de  objetos  a  partir  de  la  linea  To,  conteniendo:) 
personal 
adl 

mailbox 

host 

fromaddress  (la  linea  from:  al  completo,  hasta  1024  caracteres) 

from[]  (devuelve  un  array  de  objetos  a  partir  de  la  linea  From,  conteniendo:) 
personal 
adl 
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mailbox 

host 

ccaddress  (la  linea  cc:  al  completo,  hasta  1024  caracteres) 
cc[]  (devuelve  un  array  de  objetos  a  partir  de  la  linea  Cc:,  conteniendo:) 
personal 
adl 

mailbox 

host 

bccaddress  (la  linea  bcc  al  completo,  hasta  1024  caracteres) 
bcc[]  (devuelve  un  array  de  objetos  a  partir  de  la  linea  Bcc,  conteniendo:) 
personal 
adl 

mailbox 

host 

reply _toaddress  (la  linea  reply_to:  al  completo,  hasta  1024  caracteres) 
reply _to[]  (devuelve  un  array  de  objetos  a  partir  de  la  linea  Reply _to, 
conteniendo:) 
personal 
adl 

mailbox 

host 

senderaddress  (la  linea  sender:  al  completo,  hasta  1024  caracteres) 
sender)]  (devuelve  un  array  de  objetos  a  partir  de  la  linea  sender,  conteniendo:) 
personal 
adl 

mailbox 

host 

return_path  (la  linea  return-path:  al  completo,  hasta  1024  caracteres) 
return_path[]  (devuelve  un  array  de  objetos  a  partir  de  la  linea  return_path, 
conteniendo:) 
personal 
adl 

mailbox 

host 

udate  (fecha  del  mensaje  en  formato  unix) 

fetchfrom  (la  linea  from  formateada  hasta  ajustarse  a  los  caracteres 
indicados  en  fromlength ) 

fetchsubject  (la  linea  subject  formateada  hasta  ajustarse  a  los  caracteres 
indicados  en  subjectlength ) 
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imap_headers  (php 3,  php 4 >=  4.0.0 

Returns  headers  for  all  messages  in  a  mailbox 

array  imap_headers  (int  imap_stream) 

Devuelve  un  array  de  cadenas  formateadas  con  informacion  de  la  cabecera.  Un  elemento  por  mensaje  de 
correo. 


imap Jistmailbox  (php 3,  php 4 >=  4 0 0 

Lee  la  lista  de  buzones 


array  imap_listmailbox  (int  imap_stream,  string  ref,  string  pat) 


Devuelve  un  array  que  contiene  los  nombres  de  los  buzones. 


imap_getmailboxes  (php 3>=  3 0 12  php 4 >=  4 0 0 

Lee  la  lista  de  buzones,  devolviendo  informacon  detallada  de  cada  uno 

array  imap_getmailboxes  (int  imap_stream,  string  ref,  string  pat) 


Devuelve  un  array  de  objetos  coneniendo  informacion  del  buzon.  Cada  objeto  tiene  los  atributos  name, 
especificando  el  nombre  completo  del  buzon;  delimiter,  que  es  el  delimitador  jerarquico  para  la 
parte  de  la  jerarqufa  donde  esta  este  buzon;  y  attributes.  Attributes  es  una  mascara  de  bits 
contra  la  que  se  puede  probar; 

•  LATT_NOINFERIORS  -  Este  buzon  no  tiene  "hijos"  (No  ha  buzones  por  debajo  de  el) 

•  LATT_NOSELECT  -  Esto  es  solo  un  contenedor,  no  un  buzon  -  No  puede  abrirlo. 

•  LATT_MARKED  -  Este  buzon  esta  marcado.  Unicamente  usado  por  UW-IMAPD. 

•  LATT_UNMARKED  -  Este  buzon  no  esta  marcado.  Unicamente  usado  por  UW-IMAPD. 
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ref  normalmente  deberfa  ser  solo  el  servidor  IMAP,  de  la  forma:  {imap_server:imap_port},  y 
pattern  especifica,  donde  en  la  estructura  jerarquica  del  buzon,  para  comenzar  abuscar.  Si  quiere  todo 
los  buzones,  pase  el  parametro  pattern  como  una  cadena  vacia. 

Hay  dos  caracteres  especiales  que  puede  pasar  como  parte  del  parametro  pattern:  and  ’%’. 

significa  que  devuelva  todos  los  buzones.  Si  pasa  el  parametro  pattern  como  obtendra  una  lista 
con  la  jerarqufa  completa  del  buzon.  %’  significa  que  devuelva  solo  el  nivel  actual.  Pasar  ’%’  en  el 
parametro  pattern  devolvera  solo  el  nivel  mas  alto  de  los  buzones;  ’~/mail/%’  en  UW_IMAPD 
devolvera  cada  buzon  del  directorio  -/mail,  pero  ninguno  de  los  subdirectories  de  ese  directorio. 


imap  listsubscribed  (php 3,  PHP 4 >=  4 .0 ,0) 


Lista  todos  los  buzones  subscritos 


array  imap_listsubscribed  (int  imap_stream,  string  ref,  string  pattern) 


Devuelve  un  array  de  todos  los  buzones  que  usted  tiene  subscritos.  Los  parametros  ref  y  pattern 
especifican  la  localizacion  desde  donde  comenzara  a  buscar  y  el  patron  que  el  nombre  del  buzon  debe 
encontrar. 


imap_getsubscribed  php 3>=  3012  php 4 >=  4.0.0 

Lista  todos  los  buzones  subscritos 

array  imap_get subscribed  (int  imap_stream,  string  ref,  string  pattern) 


Esta  funcion  es  identica  a  imap_getmailboxes '),  excepto  que  esta  solo  devuelve  los  buzones  a  los  que 
esta  subscrito  el  usuario. 


imap_mail_copy  (php 3,  php 4 >=  4.0.0) 

Copia  los  mensajes  especificados  a  un  buzon 

int  imap_mail_copy  (int  imap_stream,  string  msglist ,  string  mbox,  int  flags) 
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Devuelve  true  si  no  hay  error  y  false  en  caso  contrario. 

Copia  los  mensajes  especificados  por  msglist  a  un  buzon  especificado.  msglist  es  un  rango  no 
numeros  de  mensajes. 

Flags  es  una  mascara  de  bit  de  uno  o  mas 

•  CP_UID  -  los  numeros  de  secuencia  contienen  UIDS 

•  CP_MOVE  -  Elimina  los  mensajes  del  buzon  actual  despues  de  copiarlos 


imap_mail_move  (php 3  php 4  >=  4 o 0) 

Mueve  los  mensajes  especificados  a  un  buzon 

int  imap_mail_move  (int  imap_stream,  string  msglist ,  string  mbox) 

Mueve  los  mensajes  especificados  por  msglist  al  buzon  especicifado.  msglist  es  un  rango  no 
numeros  de  mensajes. 

Devuelve  true  si  no  hay  error  y  false  en  caso  contrario. 

imapnummsg  (PHP  3,  PHP  4  >=  4.0.0) 

Informa  del  numero  de  mensajes  en  el  buzon  actual 

int  imap_num_msg  (int  imap_stream) 

Devuelve  el  numero  de  mensajes  en  el  buzon  actual. 

imap_num_recent  (PHP  3,  PHP  4  >=  4.0.0) 

Informa  el  numero  de  mensajes  recientes  en  el  buzon  actual 

int  imap_num_recent  (int  imap_stream ) 

Devuleve  el  numero  de  mensajes  recientes  en  el  buzon  actual. 
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imap_open  (PHP3,  PHP  4  >=  4.0.0) 

Abre  una  sesion  IMAP 

int  imap_open  (string  mailbox ,  string  username,  string  password,  int  flags ) 

Devuleve  la  sesion  IMAP  si  no  hay  error  y  false  en  caso  contrario.  Esta  funcion  tambien  puede  ser 
usada  para  abrir  sesiones  con  servidores  POP3  y  NNTP  Para  conectarse  a  un  servidor  IMAP  escuchando 
por  el  puerto  143  en  una  maquina  local,  haga  lo  siguiente: 

$mbox  =  imap_open ( " { localhost : 14 3 } INBOX" , "user_id" ,  "password" ) ; 

Para  conectarse  a  un  servidor  POP3  escuchando  por  el  puerto  110,  use: 

$mbox  =  imap_open ( " { localhost/pop3 : 110 } INBOX" , "user_id" ,  "password" ) ; 

Para  conectarse  a  un  servidor  NNTP  escuchando  por  el  puerto  119,  use: 

$nntp  =  imap_open ( " { localhost /nntp : 11 9 } comp . test " , " " , " " ) ; 

Para  conectarse  a  un  servidor  remoto  sustituya  "localhost",  por  el  nombre  o  direction  IP  del  servidor  al 
cual  quiere  conectarse. 

Las  opciones  son  una  mascara  de  bit  con  una  o  mas  de  los  siguientes: 

•  OP_READONLY  -  Abre  el  buzon  en  modo  de  solo  lectura 

•  OP_ANONYMOUS  -  No  usa  o  actualiza  un  .newsrc  para  las  noticias 

•  OP_HALFOPEN  -  Para  nombres  IMAP  y  NNTP,  abre  una  conexion  pero  no  abre  un  buzon 

•  CL_EXPUNGE  -  Purga  automaticamente  el  buzon  antes  de  cerrar  la  sesion 


imap_ping  (PHP  3,  PHP  4  >=4.0.0) 

Comprueba  si  la  sesion  IMAP  esta  aun  activa 

int  imap  ping  (int  imap_stream) 


Devuelve  true  si  la  sesion  esta  activa,  false  en  caso  contrario. 
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La  funcion  imap_ping()  pings  the  stream  to  see  it  is  still  active.  Esto  puede  descubrir  que  hay  correo 
nuevo;  este  es  el  metodo  preferido  para  hacer  una  comprobacion  periodica  del  buzon,  asi  como  para 
mantener  activa  sesiones  en  servidores  que  tienen  inactivity  timeout. 


imap_renamemailbox  (php 3,  php 4 >=  4.0.0 


Renombra  un  buzon 


int  imap_renamemailbox  (int  imap_stream,  string  old_mbox,  string  new_mbox) 


Esta  funcion  renombra  un  buzon  (ver  imap_opcn ')  para  el  formato  del  parametro  mbox). 
Devuelve  true  si  no  hay  error  y  false  en  caso  contrario. 

Ver  Tambien  imap_createmailbox')  and  imap_deletemailbox'). 


imap_reopen  (PHP  3,  PHP  4  >=  4.0.0) 

Reabre  una  sesion  IMAP  a  un  nuevo  buzon 

int  imap_reopen  (string  imap_stream,  string  mailbox  [,  string  flags]) 


Devuelve  true  si  no  hay  error  y  false  en  caso  contrario. 

Esta  funcio  reabre  la  sesion  especificada  con  un  nuevo  buzon. 

Las  opciones  son  mascaras  de  bit  con  una  o  mas  de  las  siguientes: 

•  OP_READONLY  -  Abre  el  buzon  en  modo  de  solo  lectura 

•  OP_ANONYMOUS  -  No  usa  o  actualiza  .newsrc  para  noticias 

•  OP_HALFOPEN  -  Para  nombres  IMAP  y  NNTP,  abre  una  conexion  pero  no  abre  el  buzon. 

•  CL_EXPUNGE  -  Expurga  automaticamente  el  buzon  antes  de  cerra  la  sesion 


imap_subscribe  (php 3,  php 4 >=  4 .0 .0) 


Subscribe  to  a  mailbox 
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int  imap_subscribe  (int  imap_stream,  string  mbox) 

Da  de  alta  un  nuevo  buzon. 

Devuleve  true  si  no  hay  error  y  false  en  caso  contrario. 

imap_undelete  (php 3,  php 4 >=  4.0.o) 

Desmarca  los  mensajes  que  estan  marcados  como  borrados 

int  imap_undelete  (int  imap_stream,  int  msg_number) 

Esta  funcion  elimina  la  marca  de  borrado  de  un  mensaje  especifico,  puesta  por  la  funcion  imap_delete\). 
Devuleve  true  si  no  hay  error  y  false  en  caso  contrario. 

imap_unsubscribe  (php  3,  php 4 >=  4 o o> 

Unsubscribe  from  a  mailbox 

int  imap_unsubscribe  (int  imap_stream,  string  mbox) 

Da  de  baja  el  buzon  especificado. 

Devuelve  true  si  no  hay  error  y  false  en  caso  contrario. 

imap_qprint  (PHP  3,  PHP  A  >=  4.0.0) 

Convierte  una  cadena  quoted-printable  a  una  cadena  de  8  bit 

string  imap_qprint  (string  string) 

Convierte  una  cadena  quoted-printable  a  una  cadena  de  8  bit 
Devuelve  una  cadena  de  8  bit  (binary) 
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imap_8bit  (PHP  3,  PHP  4  >=  4.0.0) 

Convierte  una  cadena  de  8bit  a  una  cadena  quoted-printable 

string  imap_8bit  (string  string) 

Convierte  una  cadena  de  8bit  a  una  cadena  quoted-printable. 

Devuelve  una  cadena  quoted-printable 

imap_binary  (PHP  3>=  3.0.2,  PHP  4  >=  4.0.0) 

Convierte  una  cadena  de  8bit  a  una  cadena  base64 

string  imap_binary  (string  string) 

Convierte  una  cadena  de  8bit  a  una  cadena  base64. 

Devuleve  una  cadena  base64. 

imap_scanmailbox  (php 3  php 4 >=  4 o 0> 

Lee  la  lista  de  buzones  y  toma  una  cadena  para  buscar  en  el  texto  del  buzon 

array  imap_scanmailbox  (int  imap_stream,  string  string) 

Devuelve  un  array  que  contiene  los  nombres  de  los  buzones  que  tienen  el  parametro  string  en  el  texto 
del  buzon. 

imap_mailboxmsginfo  <php 3>=  302  php 4 >=  4 0 o 

Obtiene  information  acerca  del  buzon  actual 

object  imap_mailboxmsginfo  (int  imap_stream) 
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Devuelve  information  acerca  del  buzon  actual.  Devuelve  false  en  caso  de  fallo. 

La  funcion  imap_mailboxmsginfo()  comprueba  el  estado  del  buzon  actual  en  el  servidor  y  devuelve  la 
information  en  un  objeto  con  las  siguientes  propiedades. 


Date  :  fecha  del  mensaje 

Driver :  driver 

Mailbox  :  nombre  del  buzon 

Nmsgs  :  numero  de  mensajes 

Recent :  numero  de  los  mensajes  recientes 

Unread  :  numero  de  los  mensajes  no  leidos 

Size  :  tamado  del  buzon 


imap_rfc822_write_address  (php  3>=  3.0.2,  php  4  >=  4  0  o> 

Devuleve  una  direction  de  correo  correctamente  formateada  dado  el  buzon,  host,  e  information  personal. 

string  imap_rf c822_write_address  (string  mailbox ,  string  host,  string 
personal ) 


Devuelve  una  direction  de  correo  correctamente  formateada,  dado  el  buzon,  host,  e  information 
personal. 


imap_rfc822_parse_adrlist  (php  3>=  3 .0 .2,  php  4  >=  4.0.0 


Examina  la  cadena  direction 


string  imap_rf c822_parse_adrlist  (string  address,  string  default_host) 


Esta  funcion  examina  la  cadena  direccion  y  para  cada  direccion,  devuelve  un  array  de  objetos.  Los  4 
objetos  son: 


mailbox  -  el  nombre  del  buzon  (username) 
host  -  el  nombre  del  ordenador 
personal  -  el  nombre  personal 
adl  -  ruta  del  dominio 
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imap_setflag_full  (PHP  3>=  3.0.3,  PHP  4  >=  4.0.0) 


Activa  flags  en  los  mensajes 


string  imap_setf lag_full  (int  stream,  string  sequence,  string  flag,  string 
options) 


Esta  funcion  attade  el  flag  especificado  al  conjunto  de  flags  activos  para  los  mensajes  en  la  secuencia 
especificada. 

Los  flags  que  puede  seleccionar  son  "WSeen",  "WAnswered",  "WFlagged",  "WDeleted",  "WDraft",  y 
"WRecent"  f  definidos  en  el  RFC2060) 

Las  opciones  son  una  mascara  de  bit  con  uno  o  mas  de  los  siguientes: 

ST_UID  El  argumento  sequence  contiene  UIDs  en  vez  de 
numeros  secuenciales 


imap_clearf  lag_f  ull  (php  3>=  3.0.3,  php  4  >=  4 .0 .0) 


Limpia  los  flags  de  los  mensajes 


string  imap_clearf lag_full  (int  stream,  string  sequence,  string  flag,  string 
options) 


Esta  funcion  elimina  el  flag  especificado  del  conjunto  de  flags  activos  para  los  mensajes  en  la  secuencia 
especificada. 

Las  opciones  son  una  mascara  de  bit  con  uno  o  mas  de  los  siguientes: 

ST_UID  El  argumento  sequence  contiene  UIDs  en  vez  de 
numeros  secuenciales 
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imap_sort  (PHP  3>=  3.0.3,  PHP  4  >=  4.0.0) 

Ordena  un  array  de  cabeceras  de  mensajes 

string  imap_sort  (int  stream,  int  criteria,  int  reverse ,  int  options) 


Devuelve  un  array  de  numeros  de  mensajes  ordenados  por  los  parametros  dados 
Rev  es  1  para  una  ordenacion  inversa. 

Criteria  puede  ser  uno  (y  solo  uno)  de  los  siguientes: 

SORTDATE  Fecha  del  mensaje 

SORTARRIVAL  Fecha  de  llegada 
SORTFROM  mailbox  in  first  From  address 
SORTSUBJECT  Asunto  del  mensaje 
SORTTO  mailbox  in  first  To  address 

SORTCC  mailbox  in  first  cc  address 

SORTSIZE  tamatto  del  mensaje  en  bytes 


Las  opciones  son  una  mascara  de  bit  con  uno  o  mas  de  los  siguientes: 

SE_UID  Devuelve  UIDs  en  vez  de  numeros  secuenciales 
SE_NOPREFETCH  No  preselecciona  los  mensajes  buscados. 


imap_fetchheader  (php  3>=  3.0.3,  php  4  >=  4.0.0 

Devuelve  la  cabecera  del  mensaje 


stringimap_fetchheader  (int  imap_stream,  int  msgno,  int  flags) 


Esta  funcion  localiza  el  formato  de  la  cabecera  RFC  822  del  mensaje  especificado  como  una  cadena  de 
texto  y  devuelve  esa  cadena  de  texto. 

The  options  are: 

FT_UID  El  argumento  msgno  es  un  UID 
FT_INTERNAL  La  cadena  devuelta  esta  en  formato  "interno", 
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sin  n ingun  intento  de  canonizar  CRLF 

FT_PREFETCHTEXT  The  RFC822.TEXT  should  be  pre-fetched  at  the 
same  time.  Esto  evita  un  extra  RTT  en  una 
conexion  IMAP  si  se  desea  un  mensaje  completo  de 
texto  (e.g.  en  una  operation  de 
"guardar  a  un  fichero  local") 


imap_uid  (PHP  3>=  3.0.3,  PHP  4  >=  4.0.0) 

Esta  funcion  devuelve  el  UID  del  numero  de  secuencia  del  mensaje  dado 

int  imap_uid  (int  imap_stream,  int  msgno ) 

Esta  funcion  devuelve  el  UID  del  numero  de  secuencia  del  mensaje  dado.  Esta  funcion  es  la  inversa  a 
imap_msgno 


imap_msgno  (PHP  3>=  3.0.3,  PHP  4  >=  4.0.0) 

Esta  funcion  devuelve  el  numero  de  secuencia  del  mensaje  para  el  UID  dado. 

int  imap_msgno  (int  imap_stream,  int  uid) 

Esta  funcion  devuelve  el  numero  de  secuencia  del  mensaje  para  el  UID  dado.  Esta  funcion  es  la  inversa  a 
imapuid). 


imap_search  (PHP  3>=  3.0.12,  PHP  4  >=  4.0.0) 

Esta  funcion  devuelve  un  array  de  mensajes  que  coinciden  con  el  criterio  de  busqueda  dado. 

array  imap_search  (int  imap_stream,  string  criteria,  int  flags ) 
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IMAP 


•  ALL  -  devuelve  todos  los  mensajes  que  coinciden  con  el  resto  del  criterio 

•  ANSWERED  -  busca  mensajes  con  el  flag  WANSWERED  activado 

•  BCC  "string"  -  busca  mensajes  con  "cadena"  en  el  campo  Bcc: 

•  BEFORE  "date"  -  busca  mensajes  con  Date:  antes  de  "date" 

•  BODY  "string"  -  busca  mensajes  con  "cadena"  en  el  cuerpo  del  mensaje 

•  CC  "string"  -  busca  mensajes  con  "cadena"  en  el  campo  Cc: 

•  DELETED  -  busca  mensajes  eliminados 

•  FLAGGED  -  busca  mensajes  con  el  flag  WFLAGGED  (sometimes  referred  to  as  Important  or  Urgent) 
activado 

•  FROM  "string"  -  busca  mensajes  con  "cadena"  en  el  campo  From: 

•  KEYWORD  "string"  -  busca  mensajes  con  "cadena"  como  una  palabra  clave 

•  NEW  -  busca  mensajes  nuevos 

•  OLD  -  busca  mensajes  viejos 

•  ON  "date"  -  busca  mensajes  con  "date"  igual  a  Date: 

•  RECENT  -  busca  mensajes  con  el  flag  WRECENT  activado 

•  SEEN  -  busca  mensajes  que  han  sido  leidos  (la  opcion  WSEEN  activada) 

•  SINCE  "date"  -  busca  mensajes  conwith  Date:  after  "date" 

•  SUBJECT  "string"  -  busca  mensajes  con  "string"  en  el  campo  Subject: 

•  TEXT  "string"  -  busca  mensajes  con  el  texto  "string" 

•  TO  "string"  -  busca  mensajes  con  "string"  en  el  campo  To: 

•  UNANSWERED  -  busca  mensajes  que  no  han  sido  respondidos 

•  UNDELETED  -  busca  mensajes  que  no  han  sido  eliminados 

•  UNFLAGGED  -  busca  mensajes  que  no  estan  flagged 

•  UNKEYWORD  "string"  -  busca  mensajes  que  no  coinciden  con  la  palabra  clave  "string" 

•  UNSEEN  -  busca  mensajes  que  no  han  sido  leidos  aun 

Por  ejemplo,  para  buscar  todos  los  mensajes  no  contestados  enviados  por  Mama,  usarfa: 
"UNANSWERED  FROM  mama".  La  busqueda  parece  ser  no  sensitiva.  Esta  lista  de  criterios  esta 
tomada  del  codigo  fuente  del  UW  c-client  y  puede  que  este  incompleta  o  sea  inexacta. 

Valores  validos  para  los  flags  son  SE_UID,  que  provoca  que  el  array  devuelto  contenga  UIDs  en  vez  de 
los  numeros  de  secuencia  de  los  mensajes 
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imap_last_error  (PHP  3>=  3.0.12,  PHP  4  >=  4.0.0) 


Esta  funcion  devuelve  el  ultimo  error  IMAP  (si  se  produjo)  que  ocurrio  durante  la  peticion  de  esta  pagina. 


string  imap_last_error  (void) 


Esta  funcion  devuelve  el  texto  completo  del  ultimo  error  IMAP  que  ocurrio  en  la  pagina  actual.  La  plia 
de  errores  The  error  stack  is  untouched;  llamando  despues  a  la  funcion  imap_last_error(),  sin  que  se 
produzca  un  error,  devolvera  el  mismo  error. 

ATENCIaN:  esta  funcion  no  esta  disponible  aun  en  PHP4. 


imap_errors  (PHP  3>=  3.0.12,  PHP  4  >=  4.0.0) 

Esta  funcion  devuelve  todos  los  errores  IMAP  (si  hubo)  que  han  occurrido  durante  la  peticion  de  la 
pagina  o  desde  que  la  pila  de  errores  se  inicializo. 

array  imap_errors  (void) 


Esta  funcion  devuelve  un  array  de  todos  los  mensajes  de  error  IMAP  generados  desde  la  ultima  llamada 
a  imap_errors(),  o  el  principio  de  la  pagina.  Cuando  se  llama  a  imap_errors(),  la  pila  de  errores  se 
inicializa. 

ATENCIaN:  esta  funcion  no  esta  disponible  aun  en  PHP4. 


imap_alerts  (PHP  3>=  3.0.12,  PHP  4  >=  4.0.0) 

Esta  funcion  devuelve  todos  los  mensajes  de  alerta  IMAP  (si  hubo)  que  han  ocurrido  durante  la  peticion 
de  la  pagina  o  desde  que  la  pila  de  alertas  fue  inicializada. 

array  imap_alerts  (void) 


Esta  funcion  devuelve  un  array  con  todos  los  mensajes  de  alerta  IMAP  generados  desde  la  ultima 
llamada  a  imap_alerts(),  o  el  comienzo  de  la  pagina.  Cuando  se  llama  a  imap_alerts(),  la  pila  de  alerta 
es  inicializada.  La  especificacion  IMAP  requiere  que  estos  mensajes  sean  pasados  al  usuario. 
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imap_status  (PHP  3>=  3.0.4,  PHP  4  >=  4.0.0) 

Esta  funcion  devuelve  el  informacion  de  estado  de  otro  buzon  distinto  al  actual. 


object  imap_status  (int  imap_stream,  string  mailbox ,  int  options) 


Esta  funcion  devuelve  un  objeto  que  contiene  informacion  de  estado.  Las  opciones  validas  son: 

•  SA_MESSAGES  -  activa  status->messages  con  el  numero  de  mensajes  en  el  buzon 

•  SA_RECENT  -  activa  status->recent  con  el  numero  de  mensajes  recientes  en  el  buzon 

•  SA_UNSEEN  -  activa  status ->unseen  con  el  numero  de  mesajes  no  leidos  (nuevos)  en  el  buzon 

•  SA_UIDNEXT  -  activa  status->uidnext  con  el  proximo  uid  a  usar  en  el  bizon 

•  SA_UIDVALIDITY  -  activa  status ->uid validity  con  una  constante  que  cambia  cuando  los  uids  del 
buzon  ya  no  son  validos 

•  SA_ALL  -  activa  todos  los  de  arriba 

status->flags  contienen  una  mascara  de  bits  la  cual  puede  ser  comprobada  contra  cualquiera  de  las 
propiedades  de  arriba. 
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XXXVIII.  Funciones  para  Informix 

El  conector  para  Informix  Online  (ODS)  7.x,  SE  7.x  y  Universal  Server  (IUS)  9.x  se  encuentra 
implementado  en  "functions/ifx.ec"  y  "functions/php3_ifx.h".  Para  ODS  7.x  esta  completado,  con  total 
soporte  para  columnas  de  tipo  BYTE  y  TEXT.  Para  IUS  9.x  esta  parcialmente  finalizado:  los  tipos  de 
datos  nuevos  estan  alii  (en  el  IUS  9.x),  pero  la  funcionalidad  para  SLOB  y  CLOB  se  encuentra  bajo 
construccion  todavfa. 

Notas  de  configuracion: 

Antes  de  ejecutar  el  guion  (script)  "configure",  asegurate  que  la  variable  "INFORMIXDIR"  ha  sido 
definida. 

Si  ejecutas  "configure  ~with_informix=yes"  entonces  el  guion  de  configuracion  detectara 
automaticamente  las  librerias  y  los  directorios  include.  Puedes  obviar  esta  deteccion  definiendo  las 
variables  de  entorno  "IFXLIBDIR",  "IFXJJBS"  y  "IFXJNCDIR".  Definiras  la  variable  de  compilacion 
condicional  "FIAVEJFXJUS"  si  la  version  de  Informix  es  9.00  o  superior. 


Algunas  notas  sobre  el  uso  de  BLOBs  (columnas  de  tipo  TEXT  y  BYTE): 

BLOBs  son  normalmente  manipulados  por  enteros,  los  cuales  representan  identificadores  de  BLOB. 
Las  consultas  de  seleccion  devuelven  un  "blob  id"  para  columnas  de  tipo  BYTE  y  TEXT.  Si  eliges 
trabajar  con  los  BLOBs  en  memoria  (con:  "ifx  blobinfile(O);")  entonces  puedes  obtener  el  contenido 
con  "string_var  =  ifx_get_blob($blob_id);".  Si  prefieres  manipularlos  en  ficheros  usa 
"ifx_blobinfile(1 ) y  "ifx_get_blob($blob_id);"  devolvera  el  nombre  del  archivo.  En  este  caso,  utiliza 
las  funciones  habituales  de  entrada  y  salida  de  ficheros  para  obtener  el  contenido  de  los  blob. 

Para  consultas  de  insercion  y  actualizacion  debes  crear  estos  identificadores  de  blob  con 
"ifx_create_blob(..);".  Entonces  pondras  los  identificadores  de  blob  en  un  array  y  sustituiras  en  la 
cadena  de  la  consulta  las  columnas  de  tipo  blob  por  una  interrogacion  (?).  Para  inserciones  y 
actualizaciones  eres  responsable  de  definir  el  contenido  de  los  blob  con  ifx_update_blob(...). 

La  conducta  de  columnas  BLOB  puede  ser  modificada  mediante  variables  de  configuracion,  las 
cuales  pueden  ser  definidas  en  tiempo  de  ejecucion  mediante  funciones. 

variable  de  configuracion:  ifx.textasvarchar 
variable  de  configuracion:  ifx.byteasvarchar 

funciones  en  tiempo  de  ejecucion: 

ifx_textasvarchar(0):  usa  identificadores  de  blob  para  columnas  de  tipo  TEXT  en  las  consultas  de 
seleccion 

ifx_byteasvarchar(0):  usa  identificadores  de  blob  para  columnas  de  tipo  BYTE  en  las  consultas  de 
seleccion 

ifx_textasvarchar(1):  devuelve  columnas  de  tipo  TEXT  como  si  fueran  de  tipo  VARCHAR,  sin  tener 
que  usar  identificadores  de  blob  en  las  consultas  de  seleccion 

ifx_byteasvarchar(1):  devuelve  columnas  de  tipo  BYTE  como  si  fueran  de  tipo  VARCHAR,  sin  tener 
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que  usar  identificadores  de  blob  en  las  consultas  de  seleccion. 

variable  de  configuracion:  ifx.blobinfile 
funcion  en  tiempo  de  ejecucion: 

ifx_blobinfile_mode(0):  devuelve  columnas  de  tipo  BYTE  en  memoria,  el  identificador  de  blob  te 
permite  obtener  el  contenido. 

ifx_blobinfile_mode(1):  devuelve  columnas  de  tipo  BYTE  en  un  fichero,  el  identificador  te  permite 
saber  el  nombre  de  dicho  archivo. 

Si  defines  ifx_text/byteasvarchar  a  1  entonces  puedes  usar  columnas  de  tipo  TEXT  y  BYTE  en  las 
consultas  de  seleccion  como  campos  de  tipo  VARCHAR,  pero  teniendo  en  cuenta  que  tendran  un 
mayor  tamano  que  el  habitual.  Ya  que  en  PHP  todas  las  cadenas  son  posibles,  esto  permite  datos 
binarios.  De  esta  forma,  se  pueden  manejar  correctamente.  La  information  devuelta  puede  contener 
cualquier  cosa,  tu  eres  responsable  del  contenido. 

Si  defines  ifx_blobinfile  a  1,  utiliza  el  nombre  del  archivo  devuelto  por  ifx_get_blob(..)  para  acceder  a 
los  contenidos  del  blobs.  En  este  caso,  ERES  REPONSABLE  DE  ELIMINAR  EL  ARCHIVO 
TEMPORAL  GENERADO  POR  INFORMIX  cuando  accedas  a  los  registros.  Cada  nueva  fila 
obtenida  creara  un  nuevo  archivo  temporal  para  cada  columna  de  tipo  BYTE. 

El  directorio  donde  se  guardan  los  archivos  temporales  puede  ser  definido  por  la  variable  de  entorno 
blobdir,  por  defecto  es  es  decir,  el  directorio  actual.  Asf,  putenv(blobdir=tmpblob”);  definira  un 
directorio  donde  se  localizaran  todos  los  ficheros  temporales  y  facilitara  su  borrado.  Todos  los 
nombres  de  los  archivos  comienzan  por  "bib". 


Recortado  (trimming)  automatico  de  datos  de  tipo  "char"  (SQLCHAR  y  SQLNCHAR): 

Puede  ser  definido  con  la  variable  de  configuracion 

ifx.charasvarchar:  si  se  define  a  1  eliminara  automaticamente  los  espacios  en  bianco  al  final  de  la 
cadena. 


Valores  null: 

La  variable  de  configuracion  ifx.nullformat  (y  en  tiempo  de  ejecucion  ifx  nullformat  j))  cuando  sea 
definida  a  true  devolvera  columnas  null  como  la  cadena  "null",  si  es  definida  a  false  entonces  la 
cadena  vacla.  Esto  permite  distinguir  entre  columnas  null  y  vaclas. 
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ifxconnect  (PHP  3>=  3.0.3,  PHP  4  >=  4.0.0) 

Abre  una  conexion  con  un  servidor  Informix 


int  ifx_connect  (string  [database] ,  string  [userid] ,  string  [password]) 


Si  tuvo  exito,  devuelve  un  identificador  de  conexion  en  otro  caso  false. 

ifx_connect()  establece  una  conexion  con  un  servidor  INFORMIX.  Todos  los  argumentos  son 
opcionales,  y  si  no  se  pasan,  se  toman  los  valores  del  fichero  de  configuracion  (ifx.default_host  para  el 
ordenador  donde  se  encuentra  el  servidor  (si  no  es  definida,  las  librerfas  de  Infomix  usaran  la  variable  de 
entorno  INFORMIXSERVER),  ifx.default_user  para  el  usuario  (userid),  ifx.default_password  para  la 
contrasena  (password)  (ninguna,  si  no  es  definida). 

Para  una  segunda  llamada  a  ifx_connect()  con  los  mismos  argumentos,  no  se  establecera  una  nueva 
conexion,  en  vez  de  eso,  el  identificador  de  enlace  de  la  conexion  abierta  sera  devuelto. 

La  conexion  con  el  servidor  sera  cerrada  tan  pronto  como  la  ejecucion  del  guion  (script)  finalice,  a 
menos  que  anteriormente  se  haya  llamando  a  ifx_close0- 

Examina  tambien  ifx_pconnect  j,  y  ifx_close  ). 

Ejemplo  1.  Conexion  a  una  base  de  datos  Informix 

$conn_id  =  ifx  pconnect  (mydb@ol_srvl ,  "imyself",  "mypassword" ) ; 


ifx_pconnect  (PHP  3>=  3.0.3,  PHP  4  >=  4.0.0) 

Abre  una  conexion  permanente  con  Informix 

int  ifx_pconnect  (string  [database] ,  string  [userid] ,  string  [password]) 


Devuelve  un  identificador  positivo  de  enlace  persistente  si  hubo  conexion,  o  false  si  se  produjo  un  error. 

ifx_pconnect()  actua  muy  parecido  a  disconnect))  con  dos  principales  diferencias. 

Esta  funcion  se  comporta  exactamente  igual  que  disconnect')  cuando  PHP  no  es  ejecutado  como  un 
modulo  de  Apache.  La  primera  diferencia  es  cuando  se  conecta,  la  funcion  intentara  encontrar  un  enlace 
(persistente)  que  exista  con  el  mismo  servidor,  usuario  y  contrasena.  Si  es  hallado,  el  identificador  del 
enlace  sera  devuelto  en  vez  de  abrir  una  nueva  conexion. 
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Segundo,  la  conexion  al  servidor  no  se  cerrara  cuando  la  ejecucion  del  guion  (script)  finalice.  En  vez  de 
esto,  la  conexion  permanecera  abierta  para  usos  futures  (ifx_close()  no  cerrara  el  enlace  creado  por 

ifx_pconnect()). 

Este  tipo  de  enlace  es,  por  tanto,  llamado  ’persistente’ 

Examina  tambien:  ifx_connect  ). 


ifxclose  (PHP  3>=  3.0.3,  PHP  4  >=  4.0.0) 
Cierra  una  conexion  con  Informix 


int  ifx_close  (int  [link_identifier]) 


Devuelve:  true  siempre. 

ifx_close()  cierra  un  enlace  a  una  base  de  datos  Informix  que  este  asociado  con  el  identificador  de  enlace 
(link_identifier).  Si  el  identificador  de  enlace  no  es  especificado,  el  ultimo  enlace  abierto  es  asumido. 

Observa  que  esto  no  es  necesario  habitualmente  ya  que  las  conexiones  no  permanentes  son  cerradas 
automaticamente  al  finalizar  el  guion  (script). 

ifx_close()  no  cerrara  enlaces  persistentes  generados  por  ifx_pconnect ')• 

Examina  tambien:  ifx_connect\),  y  ifx_pconnect'). 

Ejemplo  1.  Cierre  de  una  conexion  a  Informix 

$conn_id  =  ifx_connect  (mydb@ol_srv,  "itsme",  "mypassword" ) ; 

. . .  algunas  consultas  y  codigo  . . . 
ifx_close ($conn_id) ; 


ifx_query  (PHP  3>=  3.0.3,  PHP  4  >=  4.0.0) 


Envfa  una  consulta  a  Informix 


int  ifx_query  (string  query,  int  [link_identifier ],  int  [cursor_type] ,  mixed 
[blobidarray ] ) 


Devuelve  un  identificador  positivo  de  resultado  si  tuvo  exito,  false  en  otro  caso. 
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Un  entero  (integer)  "result_id"  usado  por  otras  funciones  para  obtener  el  resultado  de  la  consulta.  Es 
definido  "affected_rows"  (registros  procesados)  y  se  puede  obtener  mediante  la  funcion 
ifx_affected_rows '). 

ifx_query()  envra  una  consulta  a  la  base  de  datos  activa  actualmente  en  el  servidor,  la  cual  esta 
representada  por  el  identificador  de  enlace  especificado  (link_identifier).  Si  el  identificador  no  es 
definido,  el  ultimo  enlace  abierto  es  asumido.  Si  el  enlace  no  se  encuentra  abierto,  ifx_connectj  es 
llamado  y  utilizado. 

Ejecuta  una  consulta  (query)  sobre  una  conexion  (link_identifier).  Un  cursor  es  definido  y 
abierto  para  las  consultas  de  seleccion.  El  parametro  opcional  tipo  de  cursor  ( cursor_type )  te 
permite  que  sea  un  cursor  de  tipo  "scroll"  y/o  "hold".  Es  una  mascara  y  puede  ser  IFX_SCROLL, 
IFX_HOLD  o  ambos.  Las  consultas  que  no  son  de  seleccion  son  ejecutadas  inmediatamente. 

Para  cualquier  tipo  de  consulta  el  numero  (estimado  o  real)  de  registros  procesados  es  guardo  y  se  puede 
obtener  mediante  itx_affected_rows  '). 

Si  tienes  columnas  BLOB  (BYTE  o  TEXT)  en  una  consulta  de  actualizacion,  puedes  anadir  un 
parametro  blobidarray  conteniendo  los  identificadores  de  blob  y  sustituir  los  valores  de  esas 
columnas  por  una  "?"  en  el  texto  de  la  consulta. 

Si  el  contenido  de  la  columna  de  tipo  TEXT  (o  BYTE)  lo  permite,  tambien  puedes  usar 
"ifx_textasvarchar(l)"  y  "ifx_byteasvarchar(l)".  Esto  supone  manejar  columnas  de  tipo  TEXT  (o  BYTE) 
como  si  fueran  columnas  normales  de  tipo  VARCHAR  (pero  teniendo  en  cuenta  que  tendran  un  mayor 
tamano  que  el  habitual),  para  consultas  de  seleccion  y  no  necesitas  preocuparte  por  los  identificadores  de 
blob. 

La  opcion  por  defecto  ifx_textasvarchar(0)  o  ifx_byteasvarchar(0)  devuelve  identificadores  de  blob 
(valores  enteros)  para  las  consultas  de  seleccion.  Puedes  obtener  el  contenido  del  blob  como  una  cadena 
o  un  fichero  con  las  funciones  para  blob  (ver  mas  adelante). 

Examina  tambien:  ifx_connect'). 

Ejemplo  1.  Mostrar  todos  los  registros  de  la  tabla  "orders"  como  una  tabla  html 

if x_textasvarchar ( 1 ) ;  //  usa  "modo  texto"  para  blobs 

$res_id  =  if x_query (" select  *  from  orders",  $conn_id) ; 
if  ( !  $res_id)  { 

printf ( "Can' t  select  orders  :  %s\n<br>%s<br>\n" ,  ifx_error ( ) ) ; 

ifx_errormsg ( ) ; 

die; 

} 

if x_htmltbl_result ( $res_id,  "border=\ " 1\ " " ) ; 
if x_f ree_result ($res_id) ; 


Ejemplo  2.  Inserta  valores  en  la  tabla  "catalog" 


//  crea  identificadores  de  blob  para  una  columna  de  tipo  byte  y  otra  t 
$textid  =  ifx_create_blob (0,  0,  "Text  column  in  memory") ; 

$byteid  =  ifx_create_blob ( 1 ,  0,  "Byte  column  in  memory") ; 

//  almacena  los  identificadores  de  blob  en  un  array  lla¬ 


mado  blobid 
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$blobidarray [ ]  =  $textid; 

$blobidarray [ ]  =  $byteid; 

//  lanza  la  consulta 

$query  =  "insert  into  catalog  (stock_num,  manu_code,  " 
"cat_descr, cat_picture)  values (1, ' HRO' , ?, ?) " ; 
$res_id  =  ifx_query ($query,  $conn_id,  $blobidarray ) ; 
if  ( !  $res_id)  { 

.  .  .  error  .  .  . 


} 


//  libera  el 

ifx_free_result ($res_id) ; 


resultado 


ifx_prepare  (PHP  3>=  3.0.4,  PHP  4  >=  4.0.0) 


Prepara  una  sentencia  SQL  para  su  ejecucion 


int  ifx_prepare  (string  query,  int  conn_id  [,  int  cursor_def,  mixed 
blobidarray ] ) 


Devuelve  un  entero  (integer)  resul  t_ici  para  usarlo  con  ifx_do().  Es  definido  "affected_rows" 
(registros  procesados)  y  se  puede  obtener  mediante  la  funcion  ifx_affected_rows'). 

Prepara  una  consulta  (query)  sobre  una  conexion  (link_identifier).  Un  cursor  es  definido  y 
abierto  para  las  consultas  de  seleccion.  El  parametro  opcional  tipo  de  cursor  ( cursor_type )  te 
permite  que  sea  un  cursor  de  tipo  "scroll"  y/o  "hold".  Es  una  mascara  y  puede  ser  IFX_SCROLL, 
IFX_HOLD  o  ambos. 

Para  cualquier  tipo  de  consulta  el  numero  estimado  de  registros  afectados  (procesados)  es  guardado  y 
puede  ser  obtenido  mediante  ifx_affected_rowsO- 

Si  tienes  columnas  BLOB  (BYTE  o  TEXT)  en  una  consulta,  puedes  anadir  un  parametro 
blobidarray  conteniendo  los  identificadores  de  blob  y  sustituir  los  valores  de  esas  columnas  por  una 
"?"  en  el  texto  de  la  consulta. 

Si  el  contenido  de  la  columna  de  tipo  TEXT  (o  BYTE)  lo  permite,  puedes  tambien  usar 
"ifx_textasvarchar(l)"  y  "ifx_byteasvarchar(l)".  Esto  supone  manejar  columnas  de  tipo  TEXT  (o  BYTE) 
como  si  fueran  columnas  normales  de  tipo  VARCHAR  (pero  teniendo  en  cuenta  que  tendran  un  mayor 
tamano  que  el  habitual),  para  consultas  de  seleccion  y  no  necesitas  preocuparte  por  los  identificadores  de 
blob. 

La  opcion  por  defecto  ifx_textasvarchar(0)  o  ifx_byteasvarchar(0)  devuelve  identificadores  de  blob 
(valores  enteros)  para  las  consultas  de  seleccion.  Puedes  obtener  el  contenido  del  blob  como  una  cadena 
o  un  fichero  con  las  funciones  para  blob  (ver  mas  adelante). 

Examina  tambien:  ifx_do'). 
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ifxdo  (PHP  3>=  3.0.4,  PHP  4  >=  4.0.0) 

Ejecuta  una  sentencia  SQL  preparada  previamente 

int  ifx_do  (int  result_id) 


Devuelve  true  si  se  realizo,  false  si  hubo  algiin  error. 

Ejecuta  una  consulta  preparada  anteriormente  o  abre  un  cursor  para  ella. 

No  libera  result_id  si  hubo  un  error. 

Tambien  define  el  numero  real  de  registros  procesados  para  consultas  que  no  sean  de  selection  y  se 
puede  obtener  mediante  ifx_affected_rows(). 

Examina  tambien:  ifx  prcpare))  (hay  un  ejemplo). 


ifxerror  (PHP  3>=  3.0.3,  PHP  4  >=  4.0.0) 


Devuelve  el  codigo  de  error  de  la  ultima  llamada  a  Informix 

string  ifx_error (void)  ; 


Los  codigos  de  error  de  Informix  (SQLSTATE  &  SQLCODE)  son  representados  como  se  especifica  a 
continuation: 

x  [SQLSTATE  =  aa  bbb  SQLCODE=cccc] 
donde  x  =  un  espacio  :  no  hubo  error 
E  :  hubo  error 
N  :  no  hay  mas  datos 
W  :  aviso 
?  :  no  definido 

Si  el  caracter  "x"  es  cualquier  otra  cosa  diferente  a  un  espacio,  SQLSTATE  y  SQLCODE  describen  el 
error  con  mayor  detalle. 

Examina  el  manual  de  Informix  para  el  significado  de  SQLSTATE  y  SQLCODE. 

Devuelve  en  una  cadena  un  caracter  describiendo  el  resultado  de  una  sentencia  y  los  valores  SQLSTATE 
y  SQLCODE  asociados  con  la  ultima  sentencia  SQL  ejecutada.  El  formato  de  la  cadena  es  "(char) 
[SQLSTATE=(dos  dfgitos)  (tres  dfgitos)  SQLCODE=(un  dfgitos)]".  El  primer  caracter  puede  ser  ’  ’  (un 
espacio)  (no  hubo  error),  ’w’  (la  sentencia  provoco  un  aviso),  ’e’  (la  consulta  produjo  un  error)  o  ’n’  (la 
sentencia  no  devolvio  ningun  dato). 

Examina  tambien:  ifx_errormsg ') 
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ifxerrormsg  (PHP  3>=  3.0.4,  PHP  4  >=  4.0.0) 

Devuelve  el  mensaje  de  error  de  la  ultima  llamada  a  Informix 

string  ifx_errormsg  ([int  errorcode ]) 

Devuelve  el  mensaje  de  error  asociado  con  el  error  mas  reciente  de  Informix.  Si  definismos  el  parametro 
opcional  "errorcode"  (codigo  de  error),  nos  dara  el  mensaje  de  error  correspondiente  a  ese  codigo. 

Examina  tambien:  ifx_error  ) 

print f ( "%s\n<br>" ,  ifx_errormsg (-201) ) ; 


ifx_affected_rows  (PHP  3>=  3.0.3,  PHP  4  >=  4.0.0) 

Obtiene  el  numero  de  registros  procesados  por  una  consulta 

int  ifx_af fected_rows  (int  result_id ) 


result_id  es  un  identificador  valido  del  resultado  de  ifx_query ')  o  ifxprepare'). 

Devuelve  el  numero  de  filas  procesadas  por  una  consulta  representada  por  un  resul  t_i d 
(identificador  de  resultado). 

Para  inserciones,  actualizaciones  y  borrados  el  numero  es  exactamente  los  registros  procesados 
(sqlerrd[2]).  Para  las  consultas  de  seleccion  es  una  estimation  (sqlerrd[0]).  No  conffes  en  el. 

Es  util  llamarla  despues  de  ejecutar  ifx  prepare  )  pues  asf  podemos  limitar  las  consultas  a  numero 
razonable  de  registros. 

Examina  tambien:  ifx_num_rows() 

Ejemplo  1.  Numero  de  registros  procesados  por  una  consulta 

$rid  =  ifx_prepare  ("select  *  from  emp  where  name  like  "  .  $name,  $connid) ; 
if  ( !  $rid)  { 

. .  .  error  .  .  . 

} 

$rowcount  =  ifx_af f ected_rows  ($rid) ; 
if  ($rowcount  >  1000)  { 

printf  ("Too  many  rows  in  result  set  (%d)\n<br>",  $rowcount);  //  Demasia- 
dos  registros  en  el  resultado 

die  ("Please  restrict  your  query<br>\n" ) ;  //  Por  favor,  re- 

stringe  tu  consulta 
} 
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ifx_getsqlca  (PHP  3>=  3.0.8,  PHP  4  >=  4.0.0) 

Despues  de  una  consulta,  obtiene  el  contenido  de  sqlca.sqlerrd[0..5] 

array  ifx_getsqlca  (int  result_id) 


result_id  es  un  identificador  valido  del  resultado  de  ifx_queryO  o  ifx_prepare(). 

Devuelve  una  seudo  fila  (array  asociativo)  con  los  valores  de  sqlca.sqlerrd[0]  a  sqlca.sqlerrd[5]  de  una 
consulta  ejecutada,  representada  esta  con  un  identificador  de  resultado  result_id. 

Para  inserciones,  actualizaciones  y  borrados  los  valores  devueltos  son  aquellos  definidos  por  el  servidor 
despues  de  que  la  consulta  sea  ejecutada.  Esto  da  acceso  al  numero  de  registros  procesados  y  al  valor  de 
una  columna  de  tipo  serial  en  una  consulta  de  insercion.  Para  consultas  de  seleccion,  los  valores  son 
guardados  cuando  se  prepara  la  sentencia.  Tambien  permite  conocer  el  numero  estimado  de  registros 
procesados.  El  uso  de  esta  funcion  evita  el  sobrecoste  de  ejecutar  la  consulta  "select 
dbinfo(’sqlca.sqlerrdx’)",  como  obtener  los  valores  guardados  por  el  conector  para  Informix  en  el 
momento  apropiado. 

Ejemplo  1.  Obtener  los  valores  sqlca.sqlerrd[x] 

/*  suponiendo  que  la  primera  columna  de  la  tabla  ' sometable'  es  de  tipo  serial  */ 

$qid  =  if x_query (" insert  into  sometable  values (0,  '2nd  column',  'another  column'  ",  $connid) 
if  (!  $qid)  { 

. .  .  error  .  .  . 

} 

$sqlca  =  ifx_getsqlca  ($qid) ; 

$serial_value  =  $sqlca [ " sqlerrdl " ] ; 

echo  "The  serial  value  of  the  inserted  row  is  :  "  .  $serial_value<br>\n" ;  //El  valor  de  tij 
rial  del  registro  insertado  es : 


ifxfetchrow  (PHP  3>=  3.0.3,  PHP  4  >=  4.0.0) 

Obtiene  registros  como  un  array  (vector)  enumerado 

array  ifx_fetch_row  (int  result_id,  mixed  [position]) 


Devuelve  un  array  (vector)  correspondiente  a  la  fila  lefda  o  false  si  no  hay  mas  registros. 
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Las  columnas  blob  son  devueltas  como  identificadores  de  blob  enteros  (integer)  para  usarlos  con 
ifx_get_blob ')  a  menos  que  hayas  usado  ifx_textasvarchar(l)  o  ifx_byteasvarchar(l),  en  cuyo  caso  los 
blobs  son  devueltos  como  cadenas  de  texto.  Devuelve  false  si  hubo  error. 

result_id  es  un  identificador  valido  del  resultado  de  ifx_query ')  o  ifx  prepare ')  (solo  para  consultas 
de  seleccion). 

position  es  un  parametro  opcional  para  una  operacion  de  lectura  sobre  un  cursor  de  tipo  "scroll": 
"NEXT"  (siguiente),  "PREVIOUS"  (anterior),  "CURRENT"  (actual),  "FIRST"  (primero),  "LAST" 
(ultimo)  o  un  numero.  Si  se  especifica  un  numero,  un  registro  concreto  es  lefdo.  Este  parametro  opcional 
es  solo  valido  para  cursores  de  tipo  scroll. 

ifx_fetch_row()  lee  el  contenido  de  un  registro  de  la  consulta  representada  por  el  identificador  de 
resultado  indicado.  La  fila  (registro)  es  devuelta  en  un  array.  Cada  columna  es  guarda  en  un  array, 
empezando  este  desde  cero. 

Las  llamadas  posteriores  a  ifx_fetch_row()  devolveran  el  registro  siguiente  en  el  resultado  de  la 
consulta,  o  false  si  no  hay  mas  filas. 

Ejemplo  1.  Leer  registros 

$rid  =  ifx_prepare  ("select  *  from  emp  where  name  like  "  .  $name, 

$connid,  IFX_SCROLL) ; 

if  ( !  $rid)  { 

. .  .  error  .  .  . 

} 

$rowcount  =  if x_af f ected_rows ( $rid) ; 
if  ($rowcount  >  1000)  { 

printf  ("Too  many  rows  in  result  set  (%d)\n<br>",  $rowcount); 
dos  registros  en  el  resultado 

die  ("Please  restrict  your  query<br>\n" ) ; 
stringe  tu  consulta 
} 

if  ( !  ifx_do  ( $rid) )  { 

.  .  .  error  .  . . 

} 

$row  =  if x_f etch_row  ($rid,  "NEXT"); 
while  (is_array ( $row) )  { 

for  (reset  (  $row) ;  $f ieldname=key ( $row) ;  next ($row) )  { 

$fieldvalue  =  $row [ $f ieldname ] ; 
printf  ("%s  =  %s,  ",  $fieldname,  $fieldvalue) ; 

} 

printf ( " \n<br> " ) ; 

$row  =  ifx_fetch_row  ($rid,  "NEXT"); 

} 

if x_f ree_result  ($rid) ; 


/ /  Demasia- 
/ /  Por  favor,  re- 
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ifx_htmltbl_result  (php  3>=  3.0.3,  php  4  >=  4  0  o> 

Muestra  todos  los  registros  de  una  consulta  en  una  tabla  HTML 

int  ifx_htmltbl_result  (int  result_id  [,  string  html_table_options] ) 


Devuelve  el  numero  de  registros  lefdos  o  false  si  hubo  error. 

Muestra  todas  las  filas  de  la  consulta  result_id  dentro  de  una  tabla  html.  El  argumento  segundo, 
opcional,  es  una  cadena  de  parametros  del  tag  <table> 

Ejemplo  1.  Mostrar  resultado  como  una  tabla  HTML 

$rid  =  ifx_prepare  ("select  *  from  emp  where  name  like  "  .  $name, 

$connid,  IFX_SCROLL) ; 

if  (!  $rid)  { 

.  .  .  error  .  .  . 

} 

$rowcount  =  if x_af f ected_rows  ($rid) ; 
if  ($rowcount  >  1000)  { 

printf  ("Too  many  rows  in  result  set  (%d)\n<br>",  $rowcount); 
dos  registros  en  el  resultado 

die  ("Please  restrict  your  query<br>\n" ) ; 
stringe  tu  consulta 
} 

if  ( !  ifx_do ($rid)  { 

. . .  error  . . . 

} 

ifx_htmltbl_result  ($rid,  "border=\ " 2\ " " ) ; 
ifx_free_result ($rid) ; 


//  Demasia- 
//  Por  favor,  re- 


ifx_fieldtypes  (PHP  3>=  3.0.3,  PHP  4  >=  4.0.0) 

Obtiene  los  campos  de  una  consulta  SQL 

array  ifx_f ieldtypes  (int  result_id) 


Dada  una  consulta  representada  por  result_id  devuelve  un  array  con  los  nombres  de  campo  como 
Haves  y  los  tipos  como  datos.  Si  no  tuvo  exito  da  false. 
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Ejemplo  1.  Nombres  y  tipos  de  campos  de  una  consulta  SQL 

$types  =  ifx_f ieldtypes  ($resultid)  ; 
if  ( !  isset  ($types) )  { 

.  .  .  error  .  .  . 

} 

for  ($i  =  0;  $i  <  count ( $types ) ;  $i++)  { 

$fname  =  key ( $types ) ; 

printf("%s  : \t  type  =  %s\n",  $fname,  $types [ $f name ] ) ; 

next ( $types ) ; 

} 


ifx  f ieldproperties  (php  3>=  3.0.3,  php 4 >=  4 .0 ,0) 

Indica  las  propiedades  de  los  campos  de  una  consulta  SQL 

array  ifx_f ieldproperties  (int  result_id) 


Dada  una  consulta  representada  por  result_id  devuelve  un  array  con  los  nombres  de  campo  como 
Haves  y  las  propiedades  como  datos.  false  es  devuelto  si  hubo  error. 

Devuelve  las  propiedades  SQL  de  cada  campo  como  un  array.  Las  propiedades  son  codificadas  asi: 
"SQLTYPE;longitud;precision;escala;ISNULLABLE"  siendo  SQLTYPE  el  tipo  de  dato  definido  en 
Informix  como  puede  ser  "SQLVCHAR"  etc.  e  ISNULLABLE  (puede  ser  nulo)  igual  a  "Y"  si  o  "N"  no. 

Ejemplo  1.  Propiedades  de  los  campos  de  una  consulta  SQL 

$properties  =  ifx_f ieldtypes  ($resultid) ; 
if  (!  isset ($properties) )  { 

.  .  .  error  .  .  . 

} 

for  ($i  =  0;  $i  <  count ( $properties ) ;  $i++)  { 

$fname  =  key  ( $properties ) ; 

printf  ("%s:\t  type  =  %s\n",  $fname,  $properties [ $f name ] )  ; 

next  ( $properties ) ; 

} 


ifx  num  fields  (PHP  3>=  3.0.3,  PHP  4  >=  4.0.0) 


Devuelve  el  numero  de  columnas  en  una  consulta 
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int  ifx_num_f ields  (int  result_id) 


Dada  una  consulta  representada  por  result_id  devuelve  el  numero  de  columnas  o  false  si  se 
produjo  un  error. 

Despues  de  preparar  o  ejecutar  una  consulta,  una  llamada  a  esta  funcion  te  da  el  numero  de  columnas  en 
la  consulta. 


ifxnumrows  (PHP  3>=  3.0.3,  PHP  4  >=  4.0.0) 
Cuenta  los  registros  ya  lefdos  de  una  consulta 

int  ifx_num_rows  (int  result_id) 


Da  el  numero  de  registros  ya  lefdos  de  una  consulta  representada  por  un  result_id  despues  de  llamar 
a  ifx_query ')  o  ifx_do(). 


ifx_free_result  (PHP  3>=  3.0.3,  PHP  4  >=  4.0.0) 

Libera  los  recursos  de  una  consulta 

int  ifx_f ree_result  (int  result_id) 


Libera  los  recursos  representados  por  el  identificador  result_id  de  una  consulta.  Devuelve  false  si 
hubo  error. 


ifx_create_char  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 

Crea  un  objeto  char 

int  ifx_create_char  (string  param) 


Crea  un  objeto  char,  param  sera  el  contenido  del  char. 
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ifx_free_char  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 

Elimina  un  objeto  char 

int  ifx_f ree_char  (int  bid) 


Borra  el  objeto  char  representado  por  el  identificador  del  char  bid.  Devuelve  false  si  se  produjo  un 
error,  en  otro  caso  true. 


ifx_update_char  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 

Actualiza  el  contenido  de  un  objeto  char 

int  ifx_update_char  (int  bid,  string  content) 


Actualiza  el  contenido  de  un  objeto  char  representado  por  su  identificador  bid.  content  es  una  cadena 
con  la  information  nueva.  Devuelve  false  si  se  produjo  un  error,  en  otro  caso  true. 


ifx_get_char  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 

Obtiene  el  contenido  de  un  objeto  char 

int  ifx_get_char  (int  bid) 


Devuelve  el  contenido  de  un  objeto  char  representado  por  su  identificador  bid. 


ifx_create_blob  (PHP  3>=  3.0.4,  PHP  4  >=  4.0.0) 

Crea  un  objeto  blob 

int  ifx_create_blob  (int  type,  int  mode,  string  param) 


Crea  un  objeto  blob. 
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type  (tipo):  1  =  TEXT,  0  =  BYTE 

mode  (modo):  0  =  el  contenido  del  objeto  blob  es  conservado  en  memoria,  1  =  el  contenido  del  objeto 
blob  es  mantenido  en  un  archivo. 

param:  si  mode  =  0:  apunta  al  contenido  en  memoria,  si  mode  =  1:  contiene  el  nombre  del  fichero. 
Devuelve  false  si  hubo  error,  en  otro  caso  el  identificador  del  nuevo  objeto  blob. 


ifx_copy_blob  (PHP  3>=  3.0.4,  PHP  4  >=  4.0.0) 

Duplica  el  objeto  blob  dado 

int  ifx_copy_blob  (int  bid) 

Duplica  el  objeto  blob  dado,  bid  es  el  identificador  del  objeto  blob  a  copiar. 
Devuelve  false  si  hubo  error,  en  otro  caso  el  identificador  del  nuevo  objeto  blob. 


ifx_free_blob  (PHP  3>=  3.0.4,  PHP  4  >=  4.0.0) 
Borra  el  objeto  blob 

int  ifx_f ree_blob  (int  bid) 


Elimina  el  objeto  blob  representado  por  el  identificador  bid.  Devuelve  false  si  se  produjo  error,  en 
otro  caso  true. 


ifx_get_blob  (PHP  3>=  3.0.4,  PHP  4  >=  4.0.0) 
Obtiene  el  contenido  de  un  objeto  blob 

int  ifx_get_blob  (int  bid) 


Devuelve  el  contenido  de  un  objeto  blob  representado  por  su  identificador  bid. 
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ifx_update_blob  (PHP  3>=  3.0.4,  PHP  4  >=  4.0.0) 
Actualiza  el  contenido  de  un  objeto  blob 

ifx_update_blob  (int  bid,  string  content) 


Actualiza  el  contenido  de  un  objeto  blob  representado  por  su  identificador  bid.  content  es  una 
cadena  con  el  nuevo  contenido.  Devuelve  false  si  hubo  error,  en  otro  caso  true. 


ifxblobinf  ile_mode  (php  3>=  3.0.4,  php  4  >=  4.0.0) 

Define  el  modo  por  defecto  para  los  blob  en  todas  las  consultas  de  seleccion 

void  ifx_blobinf ile_mode  (int  mode ) 


Define  el  modo  por  defecto  para  los  blob  en  todas  las  consultas  de  seleccion.  El  modo  (mode)  "0"  quiere 
decir  que  guarda  en  memoria  los  blobs  de  tipo  BYTE  y  modo  "1"  significa  guardarlos  en  un  archivo. 


ifxtextasvarchar  (php  3>=  3.0.4,  php  4  >=  4.0.0 

Define  el  modo  por  defecto  para  los  campos  de  tipo  text 

void  ifx_textasvarchar  (int  mode) 


Define  el  modo  por  defecto  para  los  campos  de  tipo  text  en  todas  las  consultas  de  seleccion.  Modo 
(mode)  "0"  devolvera  un  identificador  de  blob  y  "1 "  dara  el  contenido  en  un  campo  de  tipo  varchar. 


ifxbyteasvarchar  (php  3>=  3.0.4,  php  4  >=  4.0.0 

Define  el  modo  por  defecto  para  los  campos  de  tipo  byte 

void  ifx_byteasvarchar  (int  mode) 
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Define  el  modo  por  defecto  para  los  campos  de  tipo  byte  en  todas  las  consultas  de  seleccion.  Modo 
(mode)  "0"  devolvera  un  identificador  de  blob  y  "  1 "  dara  el  contenido  en  un  campo  de  tipo  varchar. 


ifxnullformat  (PHP  3>=  3.0.4,  PHP  4  >=  4.0.0) 

Define  el  valor  por  defecto  cuando  se  leen  valores  nulos 

void  ifx_nullformat  (int  mode) 


Define  el  valor  por  defecto  cuando  se  leen  valores  nulos.  Modo  (mode)  "0"  devuelve  y  modo  "1" 
devuelve  "null". 


ifxus_create_slob  (PHP  3>=  3.0.4,  PHP  4  >=  4.0.0) 


Crea  un  objeto  slob  y  lo  abre 


int  ifxus_create_slob  (int  mode) 


Crea  un  objeto  slob  y  lo  abre.  Modos:  1  =  LO_RDONLY,  2  =  LO_WRONLY,  4  =  LO_APPEND,  8  = 
LO_RDWR,  16  =  LO_BUFFER,  32  =  LO_NOBUFFER  o  una  combination  de  ellos.  Tambien  puedes 
usar  nombres  de  constantes  IFX_LO_RDONLY,  IFX_LO_WRONLY,  etc.  Devuelve  false  si  hubo 
error,  en  otro  caso  el  identificador  del  nuevo  objeto  slob. 


ifx_free_slob  (unknown) 

Elimina  un  objeto  slob 

int  ifxus_f ree_slob  (int  bid) 

Borra  un  objeto  slob,  bid  es  el  identificador  del  objeto  slob.  Devuelve  false  si  hubo  error,  true  en 
otro  caso. 
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ifxus_close_slob  (PHP  3>=  3.0.4,  PHP  4  >=  4.0.0) 

Cierra  un  objeto  slob 

int  ifxus_close_slob  (int  bid) 


Cierra  un  objeto  slob  representado  por  su  identificador  de  slob  bid.  Devuelve  false  si  hubo  error, 
true  en  otro  caso. 


ifxus_open_slob  (PHP  3>=  3.0.4,  PHP  4  >=  4.0.0) 

Abre  un  objeto  slob 

int  ifxus_open_slob  (long  bid,  int  mode) 

Abre  un  objeto  slob,  bid  sera  un  identificador  de  slob  que  valido.  Modos:  1  =  LO_RDONLY,  2  = 
LO_WRONLY,  4  =  LO_APPEND,  8  =  LO_RDWR,  16  =  LO_BUFFER,  32  =  LO_NOBUFFER  o  una 
combination  de  ellos.  Devuelve  false  si  hubo  error,  en  otro  caso  el  identificador  del  nuevo  objeto  slob. 


ifxus_tell_slob  (PHP  3>=  3.0.4,  PHP  4  >=  4.0.0) 

Devuelve  el  fichero  actual  o  la  posicion  en  memoria 

int  ifxus_tell_slob  (long  bid) 

Devuelve  el  fichero  actual  o  la  posicion  en  memoria  de  un  objeto  slob  abierto,  bid  sera  un  identificador 
de  slob  valido.  Si  hubo  error  entonces  da  false. 


ifxus_seek_slob  (PHP  3>=  3.0.4,  PHP  4  >=  4.0.0) 


Define  el  fichero  o  posicion  en  memoria 


int  ifxus_seek_blob  (long  bid,  int  mode,  long  offset) 
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Define  el  fichero  o  position  en  memoria  de  un  objeto  slob  abierto,  bid  sera  un  identificador  de  slob 
valido.  Modos  (mode):  0  =  LO_S EEK_S ET,  1  =  LO_SEEK_CUR,  2  =  LO_SEEK_END  y  offset  es  el 
desplazamiento  en  bytes.  Si  hubo  error  entonces  da  false. 


ifxus_read_slob  (PHP  3>=  3.0.4,  PHP  4  >=  4.0.0) 

Lee  un  numero  de  bytes  (nbytes)  de  un  objeto  slob 

int  ifxus_read_slob  (long  bid,  long  nbytes) 


Lee  un  numero  de  bytes  (nbytes)  de  un  objeto  slob,  bid  es  un  identificador  de  slob  valido  y  nbytes  es 
el  numero  de  bytes  a  leer.  Devuelve  false  si  hubo  error,  sino  la  cadena. 


ifxus_write_slob  (PHP  3>=  3.0.4,  PHP  4  >=  4.0.0) 

Escribe  una  cadena  en  un  objeto  slob 

int  ifxus_write_slob  (long  bid,  string  content ) 


Escribe  una  cadena  en  un  objeto  slob,  bid  es  un  identificador  de  slob  valido  y  content  el  contenido  a 
escribir.  Devuelve  false  si  hubo  error,  sino  el  numero  de  bytes  escritos. 


496 


XXXIX.  Funciones  InterBase 


497 


InterBase 


ibase_connect  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 


ibase_connect  ( ) 


ibase_pconnect  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 


ibase_pconnect  ( ) 


ibase_close  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 


ibase_close  ( ) 


ibase_query  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 


ibase_query  ( ) 


ibase_fetch_row  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 


ibase_f etch_row  ( ) 
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ibase  free  result  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 


ibase_f ree_result  ( ) 


ibase_prepare  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 


ibase_prepare  ( ) 


ibase_bind  (3.0.6 -3.0.7  only) 


ibase_bind  ( ) 


ibase_execute  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 


ibase_execute  ( ) 


ibase_f  ree_query  <php  3>=  s.o.e,  php  4  >=  4  o  o> 


ibase_f ree_query  ( ) 
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ibase_timefmt  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 


ibase_timefmt  ( ) 


500 


XL.  Ingres  II  functions 


Aviso 

This  module  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  these 
functions,  these  function  names,  in  concreto  ANYTHING  documented  here  can 
change  in  a  future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this 
module  at  your  own  risk. 


These  functions  allow  you  to  access  Ingres  II  database  servers. 

In  order  to  have  these  functions  available,  you  must  compile  php  with  Ingres  support  by  using  the 
— with-ingres  option.  You  need  the  Open  API  library  and  header  files  included  with  Ingres  II.  If  the 
H_SYSTEM  environment  variable  isn’t  correctly  set  you  may  have  to  use  — with-ingres=DiR  to 
specify  your  Ingres  installation  directory. 

When  using  this  extension  with  Apache,  if  Apache  does  not  start  and  complains  with  "PHP  Fatal  error: 
Unable  to  start  ingres_ii  module  in  Unknown  on  line  0"  then  make  sure  the  environement  variable 
H_SYSTEM  is  correctly  set.  Adding  "export  II_SYSTEM="/home/ingres/H"  in  the  script  that  starts 
Apache,  just  before  launching  httpd,  should  be  fine. 

Nota:  If  you  already  used  PHP  extensions  to  access  other  database  servers,  note  that  Ingres 
doesn’t  allow  concurrent  queries  and/or  transaction  over  one  connection,  thus  you  won't  find  any 
result  or  transaction  handle  in  this  extension.  The  result  of  a  query  must  be  treated  before  sending 
another  query,  and  a  transaction  must  be  commited  or  rolled  back  before  opening  another 
transaction  (which  is  automaticaly  done  when  sending  the  first  query). 
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ingres_connect  (PHP  4  >=  4.0.2) 


Open  a  connection  to  an  Ingres  II  database. 


resource  ingres_connect  ([string  database  [,  string  username  [,  string 
password] ] ] ) 


Returns  a  Ingres  II  link  resource  on  success,  or  false  on  failure. 

ingres_connect()  opens  a  connection  with  the  Ingres  database  designated  by  database,  which  follows 
the  syntax  [node_id:  :  ]  dbname  [ / svr_class ] . 

If  some  parameters  are  missing,  ingres_connect()  uses  the  values  in  php .  ini  for 

Ingres .  default_dat abase,  Ingres .  default_user  and  Ingres .  default_password. 

The  connection  is  closed  when  the  script  ends  or  when  ingres_close ')  is  called  on  this  link. 

All  the  other  ingres  functions  use  the  last  opened  link  as  a  default,  so  you  need  to  store  the  returned  value 
only  if  you  use  more  than  one  link  at  a  time. 

Ejemplo  1.  ingres_connect()  example 


<?php 

$link  =  ingres_connect  ("mydb",  "user",  "pass") 
or  die  ("Could  not  connect") ; 
print  ("Connected  successfully"); 
ingres_close  ($link) ; 

?> 


Ejemplo  2.  ingres_connect()  example  using  default  link 

<?php 

ingres_connect  ("mydb",  "user",  "pass") 
or  die  ("Could  not  connect"); 
print  ("Connected  successfully"); 
ingres_close  (); 

?> 


See  also  ingres  pconnect  ),  and  ingres_close'). 


ingres_pconnect  (PHP  4  >=  4.0.2) 


Open  a  persistent  connection  to  an  Ingres  II  database. 
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password] ] ] ) 


Ingres  II 


Returns  a  Ingres  II  link  resource  on  success,  or  false  on  failure. 

See  ingres_connect)  for  parameters  details  and  examples.  There  are  only  2  differences  between 
ingres_pconnect()  and  ingres_connect ') :  First,  when  connecting,  the  function  will  first  try  to  find  a 
(persistent)  link  that’s  already  opened  with  the  same  parameters.  If  one  is  found,  an  identifier  for  it  will 
be  returned  instead  of  opening  a  new  connection.  Second,  the  connection  to  the  Ingres  server  will  not  be 
closed  when  the  execution  of  the  script  ends.  Instead,  the  link  will  remain  open  for  future  use 
(ingres_close  )  will  not  close  links  established  by  ingres_pconnect()).  This  type  of  link  is  therefore 
called  ’persistent’. 

See  also  ingres_connect[),  and  ingres_c!ose '). 


ingres_close  (php  4  >=  4  o  2) 

Close  an  Ingres  II  database  connection 

boolingres_close  ([resource  link]) 

Returns  true  on  success,  or  false  on  failure. 

ingres_close()  closes  the  connection  to  the  Ingres  server  that’s  associated  with  the  specified  link.  If  the 
link  parameter  isn’t  specified,  the  last  opened  link  is  used. 

ingres_close()  isn’t  usually  necessary,  as  it  won’t  close  persistent  connections  and  all  non-persistent 
connections  are  automatically  closed  at  the  end  of  the  script. 

See  also  ingres_connccC),  and  ingres_pconnect'). 


ingres_query  (PHP  4  >=  4.0.2) 

Send  a  SQL  query  to  Ingres  II 

boolingres_query  (string  query  [,  resource  link]) 

Returns  true  on  success,  or  false  on  failure. 

ingres_query()  sends  the  given  query  to  the  Ingres  server.  This  query  must  be  a  valid  SQL  query  (see 
the  Ingres  SQL  reference  guide) 
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The  query  becomes  part  of  the  currently  open  transaction.  If  there  is  no  open  transaction,  ingres_query() 
opens  a  new  transaction.  To  close  the  transaction,  you  can  either  call  ingres_commit ')  to  commit  the 
changes  made  to  the  database  or  ingres_rollbackO  to  cancel  these  changes.  When  the  script  ends,  any 
open  transaction  is  rolled  back  (by  calling  ingres_mllback')).  You  can  also  use  i ngres_autocommit ') 
before  opening  a  new  transaction  to  have  every  SQL  query  immediatly  commited. 

Some  types  of  SQL  queries  can’t  be  sent  with  this  function  : 

•  close  (see  ingres_close,)). 

•  commit  (see  ingres_commit’)). 

•  connect  (see  ingres_connect')). 

•  disconnect  (see  ingres_close')). 

•  get  dbevent 

•  prepare  to  commit 

•  rollback  (see  ingres_rollback ')). 

•  savepoint 

•  set  autocommit  (see  ingres_autocommit')). 

•  all  cursor  related  queries  are  unsupported 


Ejemplo  1.  ingres_query()  example 

<?php 

ingres_connect  ($database,  $user,  $password) ; 

ingres_query  ("select  *  from  table"); 
while  ($row  =  ingres_f etch_row ( ) )  { 

echo  $row [ 1 ] ; 
echo  $row [ 2 ] ; 

} 

?> 


See  also  ingres_fetch_array'),  ingres_fetch_object  j,  ingres_fetch_row(),  ingres_commit'), 
ingres_rollback  [)  and  i  ngres_autocomm  it  ')■ 


i  n  g  res_n  u  mrows  (PHP  4  >=  4.0.2) 

Get  the  number  of  rows  affected  or  returned  by  the  last  query 

intingres_num_rows  ([resource  link]) 
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For  delete,  insert  or  update  queries,  ingres_num_rows()  returns  the  number  of  rows  affected  by  the 
query.  For  other  queries,  ingres_num_rows()  returns  the  number  of  rows  in  the  query’s  result. 


Nota:  This  function  is  mainly  meant  to  get  the  number  of  rows  modified  in  the  database.  If  this 
function  is  called  before  using  ingres_fetch_array;),  ingres_fetch_object;)  or  ingres_fetch_row;)  the 
server  will  delete  the  result's  data  and  the  script  won’t  be  able  to  get  them. 

You  should  instead  retrieve  the  result’s  data  using  one  of  these  fetch  functions  in  a  loop  until  it 
returns  false,  indicating  that  no  more  results  are  available. 


See  also  ingres_query  ),  i ngres_fetc h_array '),  ingres_fetch_ohject  j  and  ingres_fetch_row  j. 

ingres_num_f  ields  (php  4  >=  4.0.2) 

Get  the  number  of  fields  returned  by  the  last  query 

intingres_num_f ields  ( [resource  link ] ) 

ingres_num_fields()  returns  the  number  of  fields  in  the  results  returned  by  the  Ingres  server  after  a  call 
to  ingres_query) 

See  also  ingres_query\),  i  ngres_fetc  h_array h,  i n g res_fetc h_o bj ec t ' )  and  i  ngres_fetc h_m w ' ) . 


ingres_f  ield_name  (php  4  >=  4  0  2) 

Get  the  name  of  a  field  in  a  query  result. 

stringingres_f ield_name  (int  index  [,  resource  link]) 


ingres_field_name()  returns  the  name  of  a  field  in  a  query  result,  or  false  on  failure. 

index  is  the  number  of  the  field  and  must  be  between  1  and  the  value  given  by  ingres  num  helds '). 

See  also  ingres_query '),  ingres_fetch_array  0,  ingres_fetch_ohject  )  and  ingres_fetch_mw 
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ingres_f  ield_type  (php  4  >=  4  o  2) 


Get  the  type  of  a  field  in  a  query  result. 


stringingres_f ield_type  (int  index  [, 


resource  link] ) 


ingres_field_type()  returns  the  type  of  a  field  in  a  query  result,  or  false  on  failure.  Examples  of  types 
returned  are  "IIAPI_BYTE_TYPE",  "IIAPI_CHA_TYPE",  "IIAPI_DTE_TYPE”,  "IIAPI_FLT_TYPE", 
"IIAPI_INT_TYPE",  "IIAPI_VCH_TYPE".  Some  of  these  types  can  map  to  more  than  one  SQL  type 
depending  on  the  length  of  the  field  (see  ingres  fiekl  length ')).  For  example  "IIAPI_FLT_TYPE"  can  be 
a  float4  or  a  float8.  For  detailed  information,  see  the  Ingres/OpenAPI  User  Guide  -  Appendix  C. 

index  is  the  number  of  the  field  and  must  be  between  1  and  the  value  given  by  ingresnumfields '). 

See  also  ingres_query  '),  i ngres_fetc h_array '),  ingres_fetch_object  )  and  ingres_fetch_mw 


ingres_field_nullable(PHP4>=4  0  2) 


Test  if  a  field  is  nullable. 


boolingres_f ield_nullable  (int  index  [, 


resource  link ] ) 


ingres_field_nullable()  returns  true  if  the  field  can  be  set  to  the  null  value  and  false  if  it  can’t. 
index  is  the  number  of  the  field  and  must  be  between  1  and  the  value  given  by  ingres  num  fields '). 
See  also  ingres_query '),  i ngres_fetc h_array '),  ingres_fetch_object  )  and  ingres_fetch_mw '). 


ingres_f  ield  Jength  (php  4  >=  4.0.2) 


Get  the  length  of  a  field. 


intingres_f ield_length  (int  index  [, 


resource  link] ) 


ingres_field_length()  returns  the  length  of  a  field.  This  is  the  number  of  bytes  used  by  the  server  to  store 
the  field.  For  detailed  information,  see  the  Ingres/OpenAPI  User  Guide  -  Appendix  C. 

index  is  the  number  of  the  field  and  must  be  between  1  and  the  value  given  by  ingres  num  fields '). 

See  also  ingres_query  '),  i ngres_fetc h_array '),  ingres_fetch_object  )  and  ingres_fetch_mw '). 
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ingres_f  ield_precision  (php  4  >=  4.0.2) 

Get  the  precision  of  a  field. 

intinqres  field  precision  (int  index  [,  resource  link]) 


ingres_field_precision()  returns  the  precision  of  a  field.  This  value  is  used  only  for  decimal,  float  and 
money  SQL  data  types.  For  detailed  information,  see  the  Ingres/OpenAPI  User  Guide  -  Appendix  C. 

index  is  the  number  of  the  field  and  must  be  between  1  and  the  value  given  by  ingresnumfields '). 

See  also  ingres_query'),  i ngres_fetc h_array [),  ingres_fetch_object  )  and  ingres_fetch_mw 


ingres_f  ield_scale  (php  4  >=  4.0.2) 


Get  the  scale  of  a  field. 


intingres_f ield_scale  (int  index  [,  resource  link]) 

ingres_field_scale()  returns  the  scale  of  a  field.  This  value  is  used  only  for  the  decimal  SQL  data  type. 
For  detailed  information,  see  the  Ingres/OpenAPI  User  Guide  -  Appendix  C. 

index  is  the  number  of  the  field  and  must  be  between  1  and  the  value  given  by  ingres  num  fields '). 
See  also  ingres_query'),  i ngres_fetc h_array '),  ingres_fetch_object  )  and  ingres_fetch_mw 


ingres_fetch_array  (php4>=4.o.2) 


Fetch  a  row  of  result  into  an  array. 


arrayingres_fetch_array  ( [int  result_type 


resource  link] ] ) 


ingres_fetch_array()  Returns  an  array  that  corresponds  to  the  fetched  row,  or  false  if  there  are  no 
more  rows. 

This  function  is  an  extended  version  of  ingres_fetch_row().  In  addition  to  storing  the  data  in  the  numeric 
indices  of  the  result  array,  it  also  stores  the  data  in  associative  indices,  using  the  field  names  as  keys. 

If  two  or  more  columns  of  the  result  have  the  same  field  names,  the  last  column  will  take  precedence.  To 
access  the  other  column(s)  of  the  same  name,  you  must  use  the  numeric  index  of  the  column  or  make  an 
alias  for  the  column. 
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ingres_query ( select  tl.fl  as  foo  t2.fl  as  bar  from  tl,  t2); 
$result  =  ingres_fetch_array ( ) ; 

$foo  =  $result [ " foo" ] ; 

$bar  =  $result ["bar"] ; 


result_type  can  be  H_NUM  for  enumerated  array,  II_ASSOC  for  associative  array,  or  II_BOTH 
(default). 

Speed-wise,  the  function  is  identical  to  ingres_fetch_objectO,  and  almost  as  quick  as  ingres_fetch_row  ) 
(the  difference  is  insignificant). 


Ejemplo  1.  ingres_fetch_array()  example 

<?php 

ingres_connect  ($database,  $user,  $password) ; 

ingres_query  ("select  *  from  table"); 
while  ($row  =  ingres_f etch_array ( ) )  { 

echo  $row [ "user_id" ] ;  #  using  associative  array 

echo  $row [ " fullname " ] ; 

echo  $row[l];  #  using  enumerated  array 

echo  $row [ 2 ] ; 

} 

?> 


See  also  ingres_query '),  ingres_num_fields '),  i n gre s_fi e I d_n am e ') ,  ingres_fetch_object ')  and 
ingres_fetch_rowO- 


i  ng  res_f  etchrow  (php  4  >=  4.0.2) 


Fetch  a  row  of  result  into  an  enumerated  array. 


arrayingres_fetch_row  ([resource  link]) 


ingres_fetch_row()  returns  an  array  that  corresponds  to  the  fetched  row,  or  false  if  there  are  no  more 
rows.  Each  result  column  is  stored  in  an  array  offset,  starting  at  offset  1. 

Subsequent  call  to  ingres_fetch_row()  would  return  the  next  row  in  the  result  set,  or  false  if  there  are 
no  more  rows. 
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Ejemplo  1.  ingres_fetch_row()  example 

<?php 

ingres_connect  ($database,  $user,  $password) ; 

ingres_query  ("select  *  from  table"); 
while  ($row  =  ingres_f etch_row ( ) )  { 

echo  $row [ 1 ] ; 
echo  $row [ 2 ] ; 

} 

?> 


See  also  i  n gre s_n u  m_fi elds'),  ingres_query  ),  i  ngres_fetc  h_array ')  and  ingres_fetch_object\). 


ingres_fetch_object  <php  4  >=  4.0.2) 


Fetch  a  row  of  result  into  an  object. 


ob jectingres_fetch_ob ject  ( [int  result_type  [,  resource  link]]) 


ingres_fetch_object()  Returns  an  object  that  corresponds  to  the  fetched  row,  or  false  if  there  are  no 
more  rows. 

This  function  is  similar  to  ingres_fetch_arrayO,  with  one  difference  -  an  object  is  returned,  instead  of  an 
array.  Indirectly,  that  means  that  you  can  only  access  the  data  by  the  field  names,  and  not  by  their  offsets 
(numbers  are  illegal  property  names). 

The  optional  argument  result_type  is  a  constant  and  can  take  the  following  values:  H_ASSOC, 
H_NUM,  and  II_BOTH. 

Speed-wise,  the  function  is  identical  to  ingres_fetch_array '),  and  almost  as  quick  as  i ngres_fetc h_row 1) 
(the  difference  is  insignificant). 


Ejemplo  1.  ingres_fetch_object()  example 

<?php 

ingres_connect  ($database,  $user,  $password) ; 
ingres_query  ("select  *  from  table"); 
while  ($row  =  ingres_f etch_ob ject ( ) )  { 

echo  $row->user_id; 
echo  $row->fullname; 

} 

?> 
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See  also  ingres_queryO,  ingres_num_fields  ),  ingre  s_field_n am e ') ,  ingres_fetch_array ')  and 
ingres_fetch_row  '). 


i  n  g  res_ro  1 1  back  (php  4  >=  4.0.2) 

Roll  back  a  transaction. 

boolingres_rollback  ([resource  link]) 


ingres_rollback()  rolls  back  the  currently  open  transaction,  actualy  canceling  all  changes  made  to  the 
database  during  the  transaction. 

This  closes  the  transaction.  A  new  one  can  be  open  by  sending  a  query  with  ingres_query 
See  also  ingres_query(),  ingres_commitO  and  ingres_autocommitO. 


ingres_commit  (PHP  4  >=  4.0.2) 

Commit  a  transaction. 


boolingres_commit  ( [resource  link ] ) 


ingres_commit()  commits  the  currently  open  transaction,  making  all  changes  made  to  the  database 
permanent. 

This  closes  the  transaction.  A  new  one  can  be  open  by  sending  a  query  with  ingres_query '). 

You  can  also  have  the  server  commit  automaticaly  after  every  query  by  calling  ingres_autocommit ') 
before  opening  the  transaction. 

See  also  ingres_query(),  ingres_mllback/)  and  ingres_autocommitO- 


ingres_autocommit  (PHP  4  >=  4.0.2) 

Switch  autocommit  on  or  off. 


boolingres_autocommit  ([resource  link]) 
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ingres_autocommit()  is  called  before  opening  a  transaction  (before  the  first  call  to  ingres_query ')  or  just 
after  a  call  to  ingres  rollback ')  or  ingres_autocommit())  to  switch  the  "autocommit"  mode  of  the  server 
on  or  off  (when  the  script  begins  the  autocommit  mode  is  off). 

When  the  autocommit  mode  is  on,  every  query  is  automaticaly  commited  by  the  server,  as  if 
ingres_commit  [)  was  called  after  every  call  to  ingres_query '). 

See  also  ingres_query '),  ingres_rollback')  and  ingres_commit'). 
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Internet  Relay  Chat  Gateway  ... 

Based  on  IRCG  (http://php.net/~sas/schumann.cx/ircg/),  from  Sascha  Schumann. 
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ircg_pconnect  (PHP  4  >=  4.0.4) 


Connect  to  an  IRC  server 

resource  ircg_pconnect  (string  username  [,  string  server_ip  [,  int 
server_port  [,  string  msg_format  [,  array  ctcp_messages  [,  array 
user_settings] ] ] ] ] ) 


ircg_pconnect()  will  try  to  establish  a  connection  to  an  IRC  server  and  return  a  connection  resource 
handle  for  further  use. 

The  only  mandatory  parameter  is  username,  this  will  set  your  initial  nickname  on  the  server. 
server_ip  and  server_port  are  optional  and  default  to  127 .0.0.1  and  6667. 

Nota:  For  now  parameter  server_ip  will  not  do  any  hostname  lookups  and  will  only  accept  IP 
addresses  in  numerical  form. 


You  can  customize  the  output  of  IRC  messages  and  events  by  selection  a  format  suing  set  previously 
created  with  i rc g_reg i s t e r_f o rm at_m e s s ag e s ' )  by  speeding  the  sets  name  in  msg_format. 

ctcp_mes sages 

user_set tings 

See  also:  ircg_disconnect[),  ircg_is_conn_ahve(),  ircg_register_format_messages '). 


ircg_fetch_error_msg  <php  4  >=  4 .0 .7rci) 

Returns  the  error  from  previous  ireg  operation 

array  ircg_fetch_error_msg  (resource  connection) 


ircg_fetch_error_msg()  returns  the  error  from  the  last  called  ireg  function. 
Nota:  Errorcode  is  stored  in  first  array  element,  errortext  in  second. 
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Ejemplo  1.  ircg_fetch_error_msg()  example 


if 


} 


(!ircg_join  ($id,  "#php"))  { 

$error  =  ircg_f etch_error_msg ( $id) ; 

print  ("Can't  join  channel  #php .  Errorcode: 

$error[0]  Description:  $error[l]"); 


ircg_set_current  (PHP  4  >=  4.0.4) 

Set  current  connection  for  output 

boolean  ircg_set_current  (resource  connection) 


Select  the  current  connection  for  output  in  this  execution  context.  Every  output  sent  from  the  server 
connected  to  by  connection  will  be  copied  to  standard  output  while  using  default  formating  or  a 
formar  string  set  specified  by  ircg_register_format_messages\)  and  selected  by 
i  rc  g_  I  o  o  l<  u  p_f o  rm  at_m  e  s  s  ag  e  s ' ) . 

See  also:  ircg_register_format_messages ')  and  ircg_lookup_format_messages '). 


ircgjoin  (PHP  4  >=4.0.4) 

Join  a  channel  on  a  connected  server 

boolean  ircg_join  (resource  connection,  string  channel ) 


Join  the  channel  channel  on  the  server  connected  to  by  connection. 


ircg_part  (PHP  4  >=  4.0.4) 

Leave  a  channel  on  server 

boolean  ircq  part  (resource  connection,  string  channel) 
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Leave  the  channel  channel  on  the  server  connected  to  by  connection. 


ircg_msg  (PHP  4  >=  4.0.4) 

Send  message  to  channel  or  user  on  server 

boolean  ircg_msg  (resource  connection,  string  recipient,  string  message  [, 
boolean  suppress] ) 

ircg_msg()  will  send  the  message  to  a  channel  or  user  on  the  server  connected  to  by  connection.  A 
recipient  starting  with  #  or  &  will  send  the  message  to  a  channel,  anything  else  will  be  interpreted 
as  a  username. 

Setting  the  optional  parameter  suppress  to  a  true  value  will  suppress  output  of  your  message  to  your 

own  connection. 


ircg_notice  (PHP  4  >=4.0.5) 

Send  a  notice  to  a  user  on  server 

boolean  ircg_notice  (resource  connection,  string  ,  string  message) 

This  function  will  send  the  message  text  to  the  user  nick  on  the  server  connected  to  by 
connection.  Query  your  IRC  documentation  of  choice  for  the  exact  difference  between  a  MSG  and  a 
NOTICE. 


ircg_nick(pHP4>=4  0  5) 

Change  nickname  on  server 

boolean  ircg_nick  (resource  connection,  string  nick) 

Change  your  nickname  on  the  given  connection  to  the  one  given  in  nick  if  possible. 
Will  return  true  on  success  and  false  on  failure. 
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ircg_topic  (PHP  4  >=  4.0.5) 

Set  topic  for  channel  on  server 

boolean  ircg_topic  (resource  connection,  string  channel ,  string  new_topic) 


Change  the  topic  for  channel  channel  on  the  server  connected  to  by  connection  to  new_topic. 


ircg_channel_mode  (php  4  >=  4.0.5) 

Set  channel  mode  flags  for  user 

boolean  ircg_channel_mode  (resource  connection,  string  channel ,  string 
mode_spec,  string  nick) 


Set  channel  mode  flags  for  channel  on  server  connected  to  by  connection.  Mode  flags  are  passed 
in  mode_spec  and  are  applied  to  the  user  specified  by  nick. 

Mode  flags  are  set  or  cleared  by  specifind  a  mode  character  and  prepending  it  with  a  plus  or  minus 
character  respectively.  E.g.  operator  mode  is  granted  by  ’+o’  and  revoked  by  ’-o’  passed  as  mode_spec. 


ircg_html_encode  <php  4  >=  4 .0 .5) 

Encodes  HTML  preserving  output 

boolean  ircg_html_encode  (string  html_string) 


Encodes  a  HTML  string  html_string  for  output.  This  feature  could  be  usable,  e.g.  if  someone  wants 
to  discuss  about  an  html  problem. 


ircg_whoiS(PHP4>=4  0  5) 

Query  user  information  for  nick  on  server 

boolean  ircg_whois  (resource  connection,  string  nick) 
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Sends  a  query  to  the  connected  server  connection  to  send  information  for  the  specified  user  nick. 

ircg_kick(pHp4>=4  0  5) 

Kick  a  user  out  of  a  channel  on  server 

boolean  ircg_kick  (resource  connection,  string  channel ,  string  nick,  string 
reason) 


Kick  user  nick  from  channel  on  server  connected  to  by  connection,  reason  should  give  a  short 
message  describing  why  this  action  was  performed. 

ircg_ignore_add  (php  4  >=  4.0.5) 

Add  a  user  to  your  ignore  list  on  a  server 

boolean  ircg_ignore_add  (resource  connection,  string  nick ) 

This  function  will  add  user  nick  to  your  ignore  list  on  the  server  connected  to  by  connection.  By 
doing  so  you  will  suppress  all  messages  from  this  user  from  being  send  to  you. 

See  also:  ircg_ignore_del'). 

ircg_ignore_del  (php4>=4.o.5) 

Remove  a  user  from  your  ignore  list  on  a  server 

boolean  ircg_ignore_del  (resource  connection,  string  nick) 

This  function  remove  user  nick  from  your  ignore  list  on  the  server  connected  to  by  connection. 

See  also:  ircg_ignore_add '). 
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ircg_disconnect  (php  4  >=  4 .0 ,4) 

Close  connection  to  server 

boolean  ircg_disconnect  (resource  connection,  string  reason) 

ircg_disconnect()  will  close  a  connection  to  a  server  previously  established  with  ircg-pconncct '). 
See  also:  ircg_pconnectO. 

i  rcg_is_con  rial  i  ve  (php  4  >=  4  0  5> 

Check  connection  status 

boolean  ircg_is_conn_alive  (resource  connection) 

ircg_is_conn_alive()  returns  true  if  connection  is  still  alive  and  working  or  false  if  the  server  no 
longer  talks  to  us. 

ircg  Jookup_format_messages  <php  4  >=  4  0  5> 

Select  a  set  of  format  strings  for  display  of  IRC  messages 

boolean  ircg_lookup_f ormat_mes sages  (string  name) 

Select  the  set  of  format  strings  to  use  for  display  of  IRC  messages  and  events.  Sets  may  be  registered 
with  ircg_register_format_messages'),  a  default  set  named  ircg  is  always  available. 

See  also:  ircg_register_format_messages ') 

ircg_register_format_messages  (php  4  >=  4  0  5> 

Register  a  set  of  format  strings  for  display  of  IRC  messages 

boolean  ircg_register_format_messages  (string  name,  array  messages ) 


518 


IRC  Gateway 


With  ircg_register_format_messages()  you  can  customize  the  way  your  IRC  output  looks  like.  You  can 
even  register  different  format  string  sets  and  switch  between  them  on  the  fly  with 
ircg_lookup_format_messages'). 

•  Plain  channel  message 

•  Private  message  received 

•  Private  message  sent 

•  Some  user  leaves  channel 

•  Some  user  enters  channel 

•  Some  user  was  kicked  from  the  channel 

•  Topic  has  been  changed 

•  Error 

•  Fatal  error 

•  Join  list  end(?) 

•  Self  part(?) 

•  Some  user  changes  his  nick 

•  Some  user  quits  his  connection 

•  Mass  join  begin 

•  Mass  join  element 

•  Mass  join  end 

•  Whois  user 

•  Whois  server 

•  Whois  idle 

•  Whois  channel 

•  Whois  end 

•  Voice  status  change  on  user 

•  Operator  status  change  on  user 

•  Banlist 

•  Banlist  end 

•  %f  -  from 

•  %t  -  to 

•  %c  -  channel 

•  %r  -  plain  message 

•  %m  -  encoded  message 
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•  %j  -  js  encoded  message 

•  1  -  mod  encode 

•  2  -  nickname  decode 

See  also:  ircg_lookup_format_messagesO. 
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There  are  two  possible  ways  to  bridge  PHP  and  Java:  you  can  either  integrate  PHP  into  a  Java  Servlet 
environment,  which  is  the  more  stable  and  efficient  solution,  or  integrate  Java  support  into  PHP.  The 
former  is  provided  by  a  SAPI  module  that  interfaces  with  the  Servlet  server,  the  latter  by  the  Java 
extension. 

PHP  4  ext/java  provides  a  simple  and  effective  means  for  creating  and  invoking  methods  on  Java  objects 
from  PHP.  The  JVM  is  created  using  JNI,  and  everything  runs  in-process.  Build  instructions  for  ext/java 
can  be  found  in  php4/ext/ java/README. 

Ejemplo  1.  Java  Example 

<?php 

//  get  instance  of  Java  class  java . lang . System  in  PHP 
$system  =  new  Java (' java . lang . System' ) ; 

/ /  demonstrate  property  access 

print  'Java  version=' . $system->getProperty (' java . version' ). '  <br>' ; 
print  'Java  vendor='  . $system->getProperty (' java . vendor' ). '  <br>' ; 

print  ' 0S=' . $system->getProperty ( ' os . name ' ) . '  '. 

$system->getProperty (' os .version' ). '  on  '. 

$system->getProperty ( ' os . arch' ) . '  <br>' ; 

//  java . util . Date  example 

$formatter  =  new  Java (' java . text . SimpleDateFormat ' , 

"EEEE,  MMMM  dd,  yyyy  'at'  h:mm:ss  a  zzzz")  ; 

print  $formatter->format (new  Java (' java . util . Date' )) ; 

?> 


Ejemplo  2.  AWT  Example 

<?php 

//  This  example  is  only  intented  to  be  run  as  a  CGI. 

$frame  =  new  Java (' java . awt . Frame' ,  'PHP'); 

$button  =  new  Java (' java . awt . Button' ,  'Hello  Java  World!'); 

$frame->add (' North' ,  $button) ; 

$f rame->validate ( ) ; 

$f rame->pack ( ) ; 

$f rame->visible  =  True; 

$thread  =  new  Java (' java . lang . Thread' ) ; 

$thread->sleep (10000) ; 

$f rame->dispose ( ) ; 

?> 
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Notes: 


•  new  Java  ( )  will  create  an  instance  of  a  class  if  a  suitable  constructor  is  available.  If  no  parameters 
are  passed  and  the  default  constructor  is  useful  as  it  provides  access  to  classes  like 

java .  lang .  System  which  expose  most  of  their  functionallity  through  static  methods. 

•  Accessing  a  member  of  an  instance  will  first  look  for  bean  properties  then  public  fields.  In  other 
words,  print  $date  .time  will  first  attempt  to  be  resolved  as  $date  .  getTime  ( ) ,  then  as 
$date . time. 

•  Both  static  and  instance  members  can  be  accessed  on  an  object  with  the  same  syntax.  Furthermore,  if 
the  java  object  is  of  type  java .  lang  .Class,  then  static  members  of  the  class  (fields  and  methods) 
can  be  accessed. 

•  Exceptions  raised  result  in  PHP  warnings,  and  null  results.  The  warnings  may  be  eliminated  by 
prefixing  the  method  call  with  an  "@"  sign.  The  following  APIs  may  be  used  to  retrieve  and  reset  the 
last  error: 

•  java_last_exception_get') 

•  j  a  va_  I  a  s  t_e  x  ce  pt  i  o  n  _c  I  e  ar ' ) 

•  Overload  resolution  is  in  general  a  hard  problem  given  the  differences  in  types  between  the  two 
languages.  The  PHP  Java  extension  employs  a  simple,  but  fairly  effective,  metric  for  determining 
which  overload  is  the  best  match. 

Additionally,  method  names  in  PHP  are  not  case  sensitive,  potentially  increasing  the  number  of 
overloads  to  select  from. 

Once  a  method  is  selected,  the  parameters  are  cooerced  if  necessary,  possibly  with  a  loss  of  data 
(example:  double  precision  floating  point  numbers  will  be  converted  to  boolean). 


•  In  the  tradition  of  PHP,  arrays  and  hashtables  may  pretty  much  be  used  interchangably.  Note  that 
hashtables  in  PHP  may  only  be  indexed  by  integers  or  strings;  and  that  arrays  of  primitive  types  in 
Java  can  not  be  sparse.  Also  note  that  these  constructs  are  passed  by  value,  so  may  be  expensive  in 
terms  of  memory  and  time. 


sapi/servlet  builds  upon  the  mechanism  defined  by  ext/java  to  enable  the  entire  PHP  processor  to  be  run 
as  a  servlet.  The  primary  advanatage  of  this  from  a  PHP  perspective  is  that  web  servers  which  support 
servlets  typically  take  great  care  in  pooling  and  reusing  JVMs.  Build  instructions  for  the  Servlet  SAPI 
module  can  be  found  in  php4/sapi /readme.  Notes: 

•  While  this  code  is  intended  to  be  able  to  run  on  any  servlet  engine,  it  has  only  been  tested  on 
Apache’s  Jakarta/tomcat  to  date.  Bug  reports,  success  stories  and/or  patches  required  to  get  this  code 
to  run  on  other  engines  would  be  appreciated. 

•  PHP  has  a  habit  of  changing  the  working  directory,  sapi/servlet  will  eventually  change  it  back,  but 
while  PHP  is  running  the  servlet  engine  may  not  be  able  to  load  any  classes  from  the  CLASSPATH 
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which  are  specified  using  a  relative  directory  syntax,  or  find  the  work  directory  used  for  administration 
and  JSP  compilation  tasks. 
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java  Jast_exception_clear  {php  4  >=  4.0.2) 

Clear  last  Java  exception 

void  java_last_exception_clear  () 

java Jast_exception_get  php  4  >=  4.0.2) 

Get  last  Java  exception 

exception  java_last_exception_get  () 

The  following  example  demonstrates  the  usage  of  Java’s  exception  handler  from  within  PHP: 

Ejemplo  1.  Java  exception  handler 
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Introduccion  a  LDAP 


LDAP  es  el  protocolo  de  acceso  a  directories  ligero  (Lightweight  Directory  Access  Protocol),  un 
protocolo  usado  para  acceder  a  "Servidores  de  Directorio".  El  directorio  es  una  clase  especial  de  base  de 
datos  que  contiene  informacion  estructurada  en  forma  de  arbol. 

El  concepto  es  similar  a  la  estructura  de  directories  de  los  discos  duros,  pero  en  este  caso,  el  directorio 
raiz  es  "El  Mundo"  y  los  subdirectorios  de  primer  nivel  son  los  "pafses".  Niveles  inferiores  de  la 
estructura  de  directorio  contienen  entradas  para  companfas,  organizaciones  o  lugares,  y  en  niveles  aun 
inferiores  se  encuentran  las  entradas  para  la  gente,  y  quizas  de  equipos  informaticos  y  documentos. 

Para  referirse  a  un  fichero  en  un  subdirectorio  del  disco  duro  se  usa  algo  como 
/usr/local/misapps/docs 


Las  barras  marcan  cada  division  en  la  referencia  al  fichero,  y  la  secuencia  es  leida  de  izquierda  a  derecha. 

El  equivalente  a  la  referencia  a  un  fichero  en  LDAP  es  el  "distinguished  name"  (nombre  distinguible), 
abreviado  como  "db".  Un  ejemplo  de  dn  podrfa  ser. 

cn=Pedro  Perez,ou=Contabilidad,o=Mi  Compafua,c=ES 


Las  comas  marcan  cada  division  en  la  referencia,  y  la  secuencia  se  lee  de  derecha  a  izquierda.  Este  dn  se 
leerfa  como  .. 

country  =  ES 

organization  =  Mi  Compafua 
organizationalUnit  =  Contabilidad 
commonName  =  Pedro  Perez 


De  la  misma  manera  que  no  hay  reglas  estrictas  sobre  como  organizar  la  estructura  de  directories  de  un 
disco  duro,  un  administrador  de  un  servidor  de  directorio  puede  establecer  cualquier  estructura  que  sea 
util  para  sus  propositos.  Sin  embargo  hay  algunos  acuerdos  tacitos  que  siempre  deben  seguirse.  El 
mensaje  es  que  no  se  puede  escribir  codigo  para  acceder  un  directorio  si  no  se  conoce  algo  de  su 
estructura,  igual  que  no  se  puede  usar  una  base  de  datos  sin  algun  conocimiento  sobre  lo  que  esta 
disponible  en  ella. 


Ejemplo  de  codigo  completo 

Recuperar  informacion  para  todas  las  entradas  donde  el  apellido  empiece  por  "P"  de  un  servidor  de 
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directorio,  mostrando  un  extracto  con  el  nombre  y  direction  de  correo  electronico. 

Ejemplo  1.  ejemplo  de  busqueda  LDAP 

<?php 

//La  secuencia  basica  para  trabajar  con  LDAP  es  conectar,  autentif icarse, 

//  buscar,  interpretar  el  resultado  de  la  busqueda  y  cerrar  la  conexion. 

echo  "<h3>Prueba  de  consulta  LDAP</h3>"; 
echo  "Conectando 

$ds=ldap_connect ( " localhost " ) ;  //  Debe  ser  un  servidor  LDAP  valido! 

echo  "El  resultado  de  la  conexion  es  " . $ds . " <p> " ; 

if  ($ds)  { 

echo  "Autentif icandose 

$r=ldap_bind ( $ds ) ;  //  Autentif icacion  anonima,  tipicamente  con 

//  acceso  de  lectura 

echo  "El  resultado  de  la  autentificacion  es  ".$r."<p>"; 
echo  "Buscando  (sn=P*) 

//  Busqueda  de  entradas  por  apellidos 

$sr=ldap_search ($ds, "o=Mi  Compania,  c=ES",  "sn=P*"); 
echo  "El  resultado  de  la  busqueda  es  ".$sr."<p>"; 

echo  "El  numero  de  entradas  devueltas  es  " . ldap_count_entries ($ds, $sr) ."<p>" 

echo  "Recuperando  entradas  ...<p>"; 

$info  =  ldap_get_entries ( $ds ,  $sr) ; 

echo  "Devueltos  datos  de  $info [ "count" ]. "  entradas : <p>" ; 

for  ($i=0;  $i<$info [ "count "] ;  $i++)  { 

echo  "dn  es :  $info[$i] ["dn"]  ."<br>"; 

echo  "La  primera  entrada  cn  es:  $info[$i]  ["cn"]  [0]  . "<br>"; 

echo  "La  primera  entrada  email  es :  $info[$i] ["mail"] [0]  ."<p>"; 

} 

echo  "Cerrando  conexion"; 
ldap_close ($ds) ; 

}  else  { 

echo  "<h4>Ha  sido  imposible  conectar  al  servidor  LDAP</h4>"; 

} 

?> 


Usando  las  llamadas  LDAP  de  PHP 

Es  necesario  conseguir  y  compilar  la  librerfas  cliente  de  LDAP  ya  sea  del  paquete  ldap-3.3  de  la 
Universidad  de  Michigan  o  del  Netscape  Directory  SDK.  Tambien  es  necesario  recompilar  PHP  con 
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soporte  LDAP  activado  para  que  la  funciones  LDAP  de  PHP  funcionen. 

Antes  de  usarse  las  llamadas  LDAP  se  debe  saber  .. 

•  El  nombre  o  direccion  del  servidor  de  directorio  que  se  va  a  usar 

•  El  "dn  base"  del  servidor  (la  parte  del  directorio  global  contenida  en  ese  servidor,  que  puede  ser  por 
ejemplo  "o=Mi  Compania,c=ES") 

•  Si  es  necesaria  contrasena  para  acceder  al  servidor  (muchos  servidores  ofrecen  acceso  de  lectura  para 
usuarios  anonimos  pero  requieren  un  password  para  cualquier  otro  acceso) 

La  secuencia  tfpica  de  llamadas  LDAP  suele  implementarse  en  aplicaciones  que  siguen  el  siguiente 
patron: 

ldap_connect()  //  establecer  la  conexion  con  el  servidor 

I 

ldap_bind()  //  login  anonimo  o  autentificado 
I 

Hacer  busquedas  o  actualizaciones  en  el  directorio 
y  mostrar  los  resultados 

I 

ldap_close()  //  Cerrar  la  conexion 


Mas  informacion 

Mucha  informacion  acerca  de  LDAP  puede  ser  consultada  en 

•  Netscape  (http://developer.netscape.com/tech/directory/) 

•  Universidad  de  Michigan  (http://www.umich.edu/~dirsvcs/ldap/index.html) 

•  Proyecto  OpenLDAP  (http://www.openldap.org/) 

•  LDAP  World  (http://elvira.innosoft.com/ldapworld) 

El  SDK  de  Netscape  contiene  una  Guta  de  Programacion  muy  util  en  formato  html. 
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LDAP 


Anade  entradas  a  un  directorio  LDAP 


int  ldap_add  (int  identificador_de_conexion,  string  dn,  array  entrada) 


Devuelve  verdadero  cuando  finaliza  correctamente  y  falso  se  produce  un  error. 

La  funcion  ldap_add()  se  usa  para  anadir  entradas  o  registros  a  un  directorio  LDAP.  El  DN 
("distinguished  name",  nombre  distinguible,  la  referenda  de  cualquier  entrada  LDAP)  es  especificado 
por  dn.  El  array  entrada  especifica  la  information  que  quiere  anadirse.  Los  valores  del  array  son 
indexados  por  sus  propios  atributos.  En  caso  de  valores  multiples  para  un  mismo  atributo,  son  indexados 
usando  enteros  empezando  con  0. 

entry["atributol"]  =  valor 
entry  [ "  atributo2"]  [0]  =  valorl 
entry  [ "  atributo2"]  [  1  ]  =  valor2 


Ejemplo  1.  Ejemplo  completo  con  login  atentificado 

<?php 

$ds=ldap_connect ( " localhost " ) ;  //  Asuraimos  que  el  servidor  LDAP  esta  en  el 

//  servidor  local 


if  ($ds)  { 

//  autentif icarse  con  el  dn  apropiado  para  tener  permisos  de  modificacion 
$r=ldap_bind ( $ds , " cn=root ,  o=Mi  Compania,  c=ES",  "secreto") ; 

/ /  prepare  data 

$info [ "cn" ] ="Pedro  Perez"; 

$info [ "sn" ] ="Pedro" ; 

$inf o [ "mail " ] =" pedro .pSalgun.sitio"; 

$info [ "ob ject class" ] =" persona" ; 

//  add  data  to  directory 

$r=ldap_add ( $ds ,  "cn=Pedro  Perez,  o=Mi  Compania,  c=ES",  $info) ; 

ldap_close ( $  ds ) ; 

}  else  { 

echo  "Ha  sido  imposible  conectar  al  servidor  LDAP"; 

} 

?> 
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ldap_mod_add  (PHP  3>=  3.0.8,  PHP  4  >=  4.0.0) 


Anade  valores  de  atributos 


int  ldap_mod_add  (int  identificador_de_conexion,  string  dn,  array  entrada) 


Devuelve  verdadero  cuando  finaliza  correctamente  y  falso  se  produce  un  error. 

Esta  funcion  anadir  uno  o  varios  atributos  al  dn  especificado.  Realiza  la  modificacion  al  nivel  de 
atributos,  en  vez  de  hacerlo  al  nivel  de  objetos.  Las  modificaciones  a  nivel  de  objeto  son  propocionadas 
por  la  funcion  ldap_add  )■ 


ldap_mod_del  (PHP  3>=  3.0.8,  PHP  4  >=  4.0.0) 


Borra  valores  de  atributos 


int  ldap_mod_del  (int  identificador_de_conexion,  string  dn,  array  entrada) 


returns  true  on  success  and  false  on  error. 

Esta  funcion  elimina  atributos  del  dn  especificado.  Realiza  la  modificacion  a  nivel  de  atributos,  en  vez  de 
hacerlo  a  nivel  de  objetos.  Las  modificaciones  a  nivel  de  objeto  son  proporcionadas  por  la  funcion 

ldap_del(). 


ldap_mod_replace  (PHP  3>=  3.0.8,  PHP  4  >=  4.0.0) 


Reemplaza  valores  de  atributos 


int  ldap_mod_replace  (int  identificador_de_conexion,  string  dn,  array 
entrada) 


Devuelve  verdadero  cuando  finaliza  correctamente  y  falso  se  produce  un  error. 

Esta  funcion  reemplaza  atributos  del  dn  especificado.  Realiza  la  modificacion  a  nivel  de  atributos,  en  vez 
de  hacerlo  a  nivel  de  objetos.  Las  modificaciones  a  nivel  de  objeto  son  proporcionadas  por  la  funcion 
ldap_modify  (). 
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ldap_bind 


(PHP  3,  PHP  4  >=  4.0.0) 


Autentifica  en  un  directorio  LDAP 


int  ldap_bind  (int  identificador_de_conexion  [,  string  rdn_del_usuario  [, 
string  contraseha ] ] ) 


Se  conecta  a  un  directorio  LDAP  con  un  RDN  y  su  contrasena.  Devuelve  verdadero  cuando  finaliza 
correctamente  y  falso  se  produce  un  error. 

ldap_bind()  se  conecta  al  directorio  con  un  determinado  usuario.  rdn_de_usuario  y  contrasena  son 
opcionales.  Si  no  son  especificados,  se  intenta  el  acceso  anonimo. 


ldap_close  (PHP  3,  PHP  4  >=  4.0.0) 

Cierra  una  conexion  a  un  servidor  LDAP 


int  ldap_close  (int  identificador_de_conexion) 


Devuelve  verdadero  cuando  finaliza  correctamente  y  falso  se  produce  un  error. 

ldap_close()  cierra  la  conexion  con  el  servidor  LDAP  asociada  con  el 

i dentifi cador_de_conexi on  especificado. 

Esta  llamada  es  identica  internamente  a  klap  unhind  ').  La  API  LDAP  usa  la  llamada  klapunhind y 
por  lo  tanto  quizas  deba  usar  esta  llamada  en  lugar  de  ldap_close(). 


ldap_connect  (PHP  3,  PHP  4  >=  4.0.0) 


Conecta  con  un  servidor  LDAP 


int  ldap_connect  ([string  nombre_host  [,  int  puerto] ] ) 


Devuelve  un  identificador  de  conexion  positivo  en  caso  de  exito,  6  falso  si  ocurre  algun  error. 

ldap_connect()  establece  una  conexion  con  el  servidor  LDAP  especificado  en  nombre_host  y 
puerto.  Ambos  argumentos  son  opcionales.  Si  no  se  especifican,  el  identificador  de  la  conexion  LDAP 
actualmente  abierta  es  devuelto.  Si  solo  es  especificado  nombre_host  el  puerto  tornado  por  defecto  es 
el  389. 
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ldap_count_entries  (php  3,  PHP  4  >=  4  o  o> 

Cuenta  el  numero  de  entradas  de  una  busqueda 

int  ldap_count_entries  (int  identificador_de_conexion,  int 
identificador_de_re suit  ado) 


Devuelve  el  numero  de  entradas  del  resultado  o  falso  si  ha  ocurrido  algun  error. 

ldap_count_entries()  devuelce  el  numero  de  entradas  almacenadas  en  el  resultado  de  operaciones  de 
busqueda  previas.  identificador_de_resultado  identifica  el  resultado  ldap  interno  al  que 
hacemos  referencia. 


Idap_delete  (PHP  3,  PHP  4  >=4.0.0) 

Borra  una  entrada  de  un  directorio 

int  ldap_delete  (int  identificador_de_conexion,  string  dn) 

Devuelve  verdadero  cuando  finaliza  correctamente  y  falso  se  produce  un  error. 
La  funcion  ldap_delete()  borra  la  entrada  particular  dn  del  directorio  LDAP. 

Idap_dn2uf  n  (php  3,  php  4  >=  4  o  o) 

Convierte  un  dn  al  formato  User  Friendly  Naming 

string  ldap_dn2ufn  (string  dn) 


La  funcion  ldap_dn2ufn()  es  usada  para  convertir  un  DN  en  un  formato  mas  amigable  para  el  usuario. 


ldap_explode_dn  (php 3,  php 4 >=  4 o o> 

Divide  un  DN  en  las  partes  que  le  componen 

array  ldap_explode_dn  (string  dn,  int  con_atributos) 
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La  funcion  ldap_explode_dn()  es  usada  para  dividir  un  DN  devuelto  por  ldap_get_dn()  en  las  partes  que 
le  componen.  Cada  parte  es  conocida  como  Relative  Distinguished  Name  (Nombre  Relativo 
Distinguible)  abreviado  como  RDN.  ldap_explode_dn()  devuelve  un  array  con  todos  esos  componentes. 
con_atributos  sirve  para  especificar  si  los  RDN  se  devuelven  solo  como  valores  o  con  sus  atributos 
tambien  (es  decir,  en  un  formato  atributo= valor).  Hay  que  poner  with_attrib  a  0  para  obtener 
tambien  los  atributos  y  a  1  para  obtener  solo  los  valores. 


Idap_f irst_attribute  (php  3,  php  4  >=  4.o.o) 


Devuelte  el  primer  atributo 


string  ldap_f irst_attribute  (int  identificador_de_conexion,  int 
identificador_de_entrada_en_resultado,  int  identificador_ber ) 


Devuelte  el  primer  atributo  en  la  entrada  o  falso  si  ocurre  algun  error. 

De  manera  similar  a  leer  entradas,  los  atributos  tambien  son  leidos  de  uno  en  uno  de  una  entrada  en 
particular  del  directorio.  ldap_first_attribute()  devuelve  el  primer  atributo  en  la  entrada  a  la  que  apunta 
el  identificador_de_entrada_en_resultado  El  resto  de  los  atributos  son  obtenidos  llamanda  a  la  funcion 
ldap_next_attribute ')  sucesivamente.  El  parametro  indetificador_ber  es  el  identificador  del 
puntero  interno  a  memoria.  Es  pasado  por  referencia.  El  mismo  indetificador_ber  es  pasado  a  la 
funcion  klap_next_attri bute ' )  que  modifica  dicho  puntero. 

Ver  tambien  ldap_get_attributes() 


ldap_f irst_entry  (php  3,  php  4  >=  4 .0 .o> 


Devuelve  el  identificador  del  primer  resultado 


int  ldap_f irst_entry  (int  identificador_de_conexion,  int 
identificador_de_re suit  ado) 


Devuelve  el  identificador  de  la  primera  entrada  del  resultado  6  falso  en  caso  de  error. 

Las  entradas  en  un  resultado  LDAP  son  leidas  secuencialmente  usando  las  funciones  ldap_first_entry() 
y  Idap  next  entry  ).  ldap_first_entry()  devuelve  el  identificador  de  la  primera  entrada  del  resultado. 
Este  identificador  es  entonces  suministrado  a  la  rutina  lap_next_entry()  pata  obtener  sucesivas  entradas 
del  resultado. 

Ver  tambien  ldap_get_entries '). 
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ldap_f ree_result  (php  3,  php  4  >=  4.0.0 

Libera  la  memoria  que  almacena  los  resultados 

int  ldap_free_result  (int  identificador_de_resultado) 


Devuelve  verdadero  cuando  finaliza  correctamente  y  falso  se  produce  un  error. 

ldap_free_result()  libera  la  memoria  reservada  internamente  para  almacenar  el  resultado  de  busquedas 
LDAP  asociada  al  identificador  identificador_de_resultado.  Toda  la  memoria  de  resultados 
es  automaticamente  liberada  al  finalizarse  la  ejecucion  de  un  script. 

Normalmente  la  memoria  reservada  para  resultados  ldap  se  libera  al  final  del  script.  En  caso  de  que  el 
script  realice  sucesivas  busquedas  que  devuelvan  conjuntos  de  resultados  grandes,  puede  utilizarse 
ldap_free_result()  para  mantener  bajo  el  uso  de  memoria  del  script  durante  su  ejecucion. 


Idap_get_attributes  <php  3,  php 4 >=  4 .0 .0) 


Obtiene  los  atributos  de  una  entrada  de  un  resultado  de  busqueda 


array  ldap_get_attributes  (int  identificador_de_conexion,  int 
identificador_de_entrada_de_resultado) 


Devuelve  una  completa  informacion  de  la  entrada  en  un  array  multidimensional  o  falso  en  caso  de  error. 

La  funcion  ldap_get_attributes()  es  usada  para  simplificar  el  leer  atributos  y  valores  de  una  entrada  de 
un  resultado  de  busqueda.  El  valor  de  retorno  es  un  array  multidimensional  de  atributos  y  sus  valores. 

Teniendo  localizado  una  entrada  especffica  en  el  directorio  se  puede  conseguir  la  informacion  que 
contiene  dicha  entrada  usando  esta  llamada.  Puede  usar  esta  funcion  para  aplicaciones  que  naveguen  por 
las  entradas  del  directorio  y/o  cuando  no  se  conoce  la  estructura  de  las  entradas  del  directorio.  En  otras 
aplicaciones  se  busca  un  atributo  especffico,  como  la  direccion  de  email  o  los  apellidos  y  no  importa  el 
resto  de  informacion  contenida.. 


valor_devuelto["count"]  =  numero  de  atributos  en  la  entrada 
valor_devuelto[0]  =  primer  atributo 
valor_devuelto[n]  =  enesimo  atributo 

valor_devuelto["atributo"]["count"]  =  numero  de  vaslores  del  atributo 
valor_devuelto["atributo"][0]  =  primer  valor  del  atributo 
valor_devuelto["atributo"][i]  =  iesimo  valor  del  atributo 
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Ejemplo  1.  Mostrar  la  lista  de  atributos  contenida  en  una  entrada  especifica  de  un  directorio 

//  $ds  es  un  identificador  de  conexion  al  directorio 

/ /  $sr  es  un  resultado  de  busqueda  valido  de  una  llamada 
/ /  anterior  a  una  de  las  funciones  de  busqueda  en  directories 
/ /  ldap . 

$entrada  =  ldap_f irst_entry ($ds,  $sr) ; 

$atributos  =  ldap_get_attributes ( $ds,  $entrada) ; 

echo  $atributos [" count "  atributos  contenidos  en  esta  entrada : <p> " ; 

for  ($i=0;  $i<$atributos [" count "] ;  $i++) 
echo  $atributos [ $i ] . "<br>" ; 


Ver  tambien  ldap_first_attribute  3  y  ldap_next_attributeO 


ldap_get_dn  (PHP  3,  PHP  4  >=  4.0.0) 


Obtiene  el  DN  de  una  entrada  de  un  resultado 


string  ldap_get_dn  (int  indent! ficador_de_conexion,  int 
indenti ficador_de_entrada_de_re suit  ado) 


Devuelve  el  DN  de  la  entrada  del  resultado  o  falso  en  caso  de  error. 

La  funcion  ldap_get_dn()  se  utiliza  para  obtener  el  DN  de  una  entrada  de  un  resultado  de  busqueda. 


Idap_get_entries  <php  3  php  4  >=  4.o.o> 


Obtiene  todas  las  entradas  de  un  resultado 


array  ldap_get_entri.es  (int  indentificador_de_conexion,  int 
indent  if icador_de_re suit  ado) 


Devuelve  una  completa  informacion  de  un  resultado  de  busqueda  en  un  array  multidimensional  o  falso 
en  caso  de  error. 
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La  funcion  ldap_get_entries()  es  usada  para  simplificar  el  leer  multiples  entradas  de  de  un  resultado  y 
despues  leer  sus  atributos  y  multiples  valores.  Toda  la  informacion  es  devuelta  por  una  llamada  a  una 
funcion  en  forma  de  array  multidimensional.  La  estructura  del  array  es  como  se  muestra  mas  abajo. 

Los  indices  de  atributos  son  convertidos  a  minusculas.  (Los  atributos  de  servidores  de  directories  son 
indiferentes  a  las  mayusculas/minusculas,  pero  no  cuando  son  usados  como  indices  de  arrays) 

valor_devuelto["count"]  =  numero  de  entradas  del  resultado 
valor_devuelto[0]  :  contiene  los  detalles  de  la  primera  entrada 

valor_devuelto[i]["dn"]  =  DN  de  la  entrada  iesima  del  resultado 

valor_devuelto[i] ["count"]  =  numero  de  atributos  de  la  entrada  iesima 
valor_devuelto[i][j]  =  jesimo  atributo  de  la  iesima  entrada  del  resultado 

valor_devuelto[i]["atributo"]  ["count"]  =  numero  de  valores  para  "atributo" 
en  la  entrada  iesima 

valor_devuelto[i]["atributo"][j]  =  jesimo  valor  de  "atributo"  en  la  entrada 
iesima 


Ver  tambien  ldap_first_entry ')  y  ldap_next_entry ') 


ldap_get_values  (php 3  php 4 >=  4.0.0) 


Obtiene  todos  los  valores  de  un  atributo  de  una  entrada 


array  ldap_get_values  (int  identificador_de_conexion,  int 
identificador_de_entrada_de_resultado,  string  atributo) 


Devuelve  un  array  de  valores  del  atributo  o  falso  en  caso  de  error. 

La  funcion  ldap_get_values()  se  utiliza  para  obtener  todos  los  valores  de  un  atributo  de  una  entrada.  La 
entrada  del  resultado  es  especificada  por  el  identificador_de_entrada_de_resultado.  El 
numero  de  valores  se  almacena  en  el  indice  "count"  del  array  devuelto.  Los  valores  individuales  se 
almacenan  con  indices  enteros  en  el  array.  El  primer  indice  es  0. 

Esta  llamada  necesita  un  identificador_de_entrada_de_resultado ,  por  lo  que  necesita  ser 
precedida  por  una  de  las  llamadas  de  busqueda  ldap  y  una  llamada  para  obtener  una  entrada  en  particular 
del  resultado. 

La  aplicacion  debe  ser  o  bien  programada  especfficamente  para  buscar  ciertos  atributos  (como  apellidos 
o  email)  o  bien  utilizar  la  funcion  ldap_get_attributes  )  para  averiguar  que  atributos  existen  para  una 
entrada  dada,  antes  de  llamar  a  ldap_get_values(). 

LDAP  permite  mas  de  un  valor  para  cada  atributo,  por  lo  que  se  puede,  por  ejemplo,  almacenar  varias 
direcciones  de  email  para  una  persona  en  el  directorio  y  nombrar  a  ese  atributo  como  "email" 
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valor_devuelto["count"]  =  numero  de  valores  del  atributo 
valor_devuelto[0]  =  primer  valor  del  atributo 
valor_devuelto[i]  =  iesimo  valor  del  atributo 

Ejemplo  1.  Listar  todos  los  valores  del  atributo  "email"  de  una  entrada  de  un  directorio 

//  $ds  es  un  identificador  de  conexion  al  directorio 

/ /  $sr  es  un  resultado  de  busqueda  valido  de  una  llamada 
/ /  anterior  a  una  de  las  funciones  de  busqueda  en  directories 
/ /  Idap . 

/ /  $entrada  es  un  identificador  de  entrada  valido  de  una  llamada 
/ /  anterior  a  una  de  las  funciones  que  devuelven  una  entrada  de 
/ /  directorio 

$valores  =  ldap_get_values ( $ds ,  $entrada, "email ") ; 

echo  $valores [ "count" ]. "  direcciones  de  email  para  esta  entrada . <p> " ; 

for  ($i=0;  $i  <  $valores ["count"] ;  $i++) 
echo  $valores  [ $ i ]  . "<br>" ; 


ldap_get_values  Jen  (php  3>=  3.0.13,  php  4  >=  4.0.0) 


Obtiene  todos  los  valores  binarios  de  un  atributo  de  una  entrada 


array  ldap_get_values_len  (int  indentificador_de_conexion,  int 
indenti ficador_de_entrada_de_resultado,  string  atributo) 


Devuelve  un  array  de  valores  del  atributo  o  falso  en  caso  de  error. 

La  funcion  ldap_get_values_len()  se  utiliza  para  obtener  todos  los  valores  de  un  atributo  de  una  entrada 
de  un  resultado  de  busqueda.  La  entrada  es  especificada  por  el 

indenti  ficador_de_entrada_de_resultado.  El  numero  de  valores  se  almacena  en  el  indice 
"count"  del  array  devuelto.  Los  valores  individuales  se  almacenan  con  indices  enteros  en  el  array.  El 
primer  mdice  es  0. 

Esta  funcion  se  utiliza  exactamente  como  ldap_get_valuesO  salvo  que  permite  manejar  datos  binarios  y 
no  cadenas  de  caracteres. 
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LDAP 


Busqueda  Single-level  (Nivel  Unico) 


int  ldap_list  (int  identificador_de_conexion,  string  dn_base ,  string  filtro 
[,  array  atributos ]) 


Devuelve  un  identificador  de  resultado  de  busqueda  o  falso  en  caso  de  error. 

ldap_list()  realiza  la  busqueda  segun  el  filtro  especificado  en  el  directorio  con  el  alcance 
LDAP_SCOPE_ONELEVEL. 

LDAP_SCOPE_ONELEVEL  significa  que  la  busqueda  solo  devuelve  information  que  se  encuentre  en 
el  nivel  inmediatamente  inferior  al  dn  base  especificado  en  la  llamada  a  la  funcion.  (Equivalente  a 
ejecutar  "Is"  en  un  unix  y  obtener  un  listado  de  ficheros  y  carpetas  en  el  directorio  de  trabajo  actual.) 

Esta  llamada  toma  un  cuarto  parametro  optional,  que  es  un  array  de  los  atributos  requeridos.  Consulte 
las  notas  de  la  funcion  Idap  search  ). 

Ejemplo  1.  Produce  una  lista  de  todas  las  unidades  organizativas  de  una  companfa 

//  $ds  es  un  identificador  de  conexion  valido. 

$dnbase  =  "o=Mi  Compania,  c=ES"; 

$solonecesito  =  arrayC'ou")  ; 

$sr=ldap_list ( $ds ,  $dnbase,  "ou=*",  $solonecesito)  ; 

$info  =  ldap_get_entries ($ds,  $sr)  ; 

for  ($i=0;  $i<$info [ "count" ] ;  $i++) 
echo  $info[$i]  ["ou"]  [0]  ; 


ldap_modify  (PHP  3,  PHP  4  >=  4.0.0) 

Modifica  una  entrada  LDAP 

int  ldap_modify  (int  identificador_de_conexion,  string  dn,  array  entrada) 

Devuelve  verdadero  cuando  finaliza  correctamente  y  falso  se  produce  un  error. 

La  funcion  ldap_modify()  se  utiliza  para  modificar  entradas  existentes  en  un  directorio  LDAP.  La 
estructura  de  la  entrada  es  igual  a  la  de  Idap  add  ). 
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ldap_next_attribute  (php  3,  php  4  >=  4.0.0 


Obtiene  el  siguiente  atributo  de  una  entrada 


string  ldap_next_attribute  (int  identificador_de_conexion,  int 
identificador_de_entrada_de_resultado,  int  identificador_ber ) 


Devuelve  el  siguiente  atributo  de  una  entrada  o  falso  en  caso  de  error. 

ldap_next_attribute()  es  llamado  para  recuperar  los  atributos  de  una  entrada.  El  estado  interno  del 
puntero  es  mantenido  por  el  identificador_ber ,  que  es  pasado  por  referenda  a  la  funcion.  La 
primera  llamada  a  ldap_next_attribute()  es  realizada  con  el 

ident  i  f  icado  r_de_ent  rada_de_re  suit  ado  devuelto  por  la  funcion  ldap_first_attribute'). 
Ver  tambien  ldap_get_attributes ') 


ldap_next_entry  (php  3,  php  4  >=  4.0.0) 


Obtiene  la  siguiente  entrada  de  un  resultado 


int  ldap_next_entry  (int  identificador_de_conexion,  int 
Ident If icado r_de_entrada_de_re suit  ado) 


Devuelve  el  identificador  de  la  siguiente  entrada  del  resultado.  Las  entradas  deben  haber  sido  leidas  al 
principio  con  Idap  fi rst  cntry  ).  Si  no  hay  mas  entradas  en  el  resultado  devuelve  falso. 

La  funcion  ldap_next_entry()  se  utiliza  para  obtener  las  entradas  almacenadas  en  un  resultado. 
Llamadas  sucesivas  a  la  funcion  ldap_next_entry()  devuelven  las  entradas  una  a  una  hasta  que  ya  no 
queden  mas  entradas.  La  primera  llamada  a  ldap_next_entry()  se  realiza  despues  de  llamar  a 
ldap_first_entry '). 

Ver  tambien  ldap_get_entriesO 


ldap_read 


(PHP  3,  PHP  4  >=4.0.0) 


Lee  una  entrada 


int  ldap_read  (int  identificador_de_conexion,  string  dn_base ,  string  filtro 
[,  array  atributos ]) 
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Devuelve  un  identificador  de  resultado  de  busqueda  o  falso  en  caso  de  error. 

ldap_read()  realiza  la  busqueda  segun  el  filtro  especificado  con  alcance  LDAP_SCOPE_BASE,  por  lo 
que  es  equivalente  a  leer  cualquier  entrada  del  directorio. 

No  se  permiten  filtros  vacios.  Si  se  pretende  obtener  absolutamente  toda  la  informacion,  se  debe  usar  un 
filtro  del  tipo  "objectClass=*".  Si  conoce  que  tipos  de  entradas  son  usadas  en  el  servidor  de  directorio  es 
conveniente  usar  el  filtro  apropiado,  como  por  ejemplo  "objectClass=inetOrgPerson". 

Esta  llamada  toma  un  cuarto  parametro  opcional  que  es  un  array  de  los  atributos  requeridos.  Consulte  las 
notas  de  la  funcion  ldap_search'). 


Idap_search  (PHP3,  PHP  4  >=  4.0.0) 


Busca  en  un  arbol  LDAP 


int  ldap_search  (int  identificador_de_conexion,  string  dn_base,  string  filtro 
[,  array  atributos ]) 


Devuelve  un  identificador  de  resultado  de  busqueda  o  falso  en  caso  de  error. 

ldap_search()  realiza  la  busqueda  segun  el  filtro  especificado  con  alcance  LDAP_SCOPE_SUBTREE. 
Esto  es  equivalente  a  buscar  en  el  directorio  entero.  dn_base  especifica  el  DN  base  para  el  directorio. 

Existe  un  cuarto  parametro  opcional  que  puede  ser  anadido  para  restringir  los  atributos  y  valores 
devueltos  por  el  servidor  a  solo  los  requeridos.  Es  mucho  mas  eficiente  que  la  accion  por  defecto  (que 
devolvera  todos  los  atributos  y  sus  valores  asociados).  El  uso  del  cuarto  parametro  debe  ser  por  tanto 
considerado  una  practica  recomendable. 

El  cuerto  parametro  es  un  array  estandar  de  PHP  con  los  atributos  requeridos,  por  ejemplo 
array("email","sn","cn").  Nota:  "dn"  siempre  es  devuelto  independientemente  de  que  tipos  de  atributos 
sean  solicitados. 

Tambien  es  necesario  resaltar  que  algunos  servidores  de  directorio  estan  configurados  para  devolver  un 
cierto  numero  de  entradas  como  maximo.  Si  esto  ocurre,  el  servidor  indicara  que  solo  devuelve  un 
conjunto  de  resultados  parcial. 

El  filtro  de  busqueda  puede  ser  simple  o  avanzado,  usando  operadores  booleanos  en  el  formato  descrito 
en  la  documentation  sobre  LDAP  (Consulte  el  Netscape  Directory  SDK 

(http://developer.netscape.com/tech/directory/)  para  obtener  completa  informacion  sobre  filtros). 

El  ejemplo  de  abajo  recupera  la  unidad  organizativa  (ou),  apellidos  nombre  comun  y  direccion  de  email 
para  todas  las  personas  de  "Mi  Companfa"  donde  los  apellidos  o  el  nombre  comun  contiene  la  subcadena 
Spersona.  Este  ejemplo  usa  un  filtro  booleano  para  indicar  al  servidor  que  busque  la  informacion  en  mas 
de  un  atributo. 

Ejemplo  1.  Busqueda  LDAP 

//  $ds  es  un  identificador  de  conexion  valido 
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//  $persona  es  todo  o  parte  del  nombre  de  una  persona,  por  ejemplo  "Pe" 
$dn  =  "o=Mi  Compania,  c=ES"; 

$filtro=" ( | ( sn=$persona* ) (givenname=$persona* ) ) 

$solonecesito  =  array (  "ou",  "sn",  "givenname",  "mail"); 

$sr=ldap_search ($ds,  $dn,  $filtro,  $solonecesito) ; 

$info  =  ldap_get_entries ($ds,  $sr) ; 

print  $info [ "count" ]. "  entradas  devueltas<p>" ; 


ldap_unbind  (php 3  php 4 >=  4 .0 ,0) 

Hace  logout  de  un  directorio  LDAP 

int  ldap_unbind  (int  identificador_de_conexion) 

Devuelve  verdadero  cuando  finaliza  correctamente  y  falso  se  produce  un  error. 
La  funcion  ldap_unbind()  hace  logout,  desautentifica  de  un  directorio  LDAP. 


Idap_err2str  (PHP  3>=  3.0.13,  PHP  4  >=  4.0.0) 

Convierte  un  codigo  numerico  de  error  LDAP  en  un  mensaje. 

string  ldap_err2str  (int  numerr) 


Devuelve  una  cadena  con  el  mensaje  de  error. 

Esta  funcion  devuelve  una  cadena  con  el  mensaje  de  error  explicativo  del  codigo  numerico  de  error 
numerr.  Aunque  los  codigos  de  error  LDAP  estan  estandarizados,  diferentes  librerfas  devuelven 
mensajes  textuales  de  error  diferentes  o  incluso  localizados.  Nunca  se  debe  comprobar  la  existencia  de 
un  error  especffico  por  el  mensaje  textual,  sino  por  el  codigo  numerico. 

Var  tambien  Idap  crrno')  y  Idap  error'). 
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Ejemplo  1.  Enumerando  todos  los  mensajes  de  error  LDAP 

<?php 

for($i=0;  $i<100;  $i++)  { 

printf ( "Error  $i :  %s<br>\n",  ldap_str2err ( $i ) ) ; 

} 

?> 


ldap_errno  (PHP  3>=  3.0.12,  PHP  4  >=  4.0.0) 

Devuelve  el  codigo  numerico  de  error  para  el  ultimo  comando  LDAP. 

int  ldap_errno  (int  identificador_de_conexion) 


Devuelve  el  codigo  de  error  del  ultimo  comando  LDAP  para  la  conexion  especificada. 

Esta  funcion  devuelve  el  codigo  numerico  de  error,  que  esta  estandarizado,  producido  por  el  ultimo 
comando  LDAP  y  en  la  conexion  especificada.  Este  numero  puede  ser  convertido  en  un  mensaje  textual 
de  error  usando  Idap_err2str'j. 

A  menos  que  decremente  el  nivel  de  alerta  en  su  fichero  php3  .  ini  (6  php .  ini)  o  anteponga  a  los 
comandos  LDAP  en  sfmbolo  @  (arroba)  para  suprimir  las  alertas  y  warnings,  los  errores  producidos 
seran  mostrados  automaticamente  en  el  codigo  HTML  generado. 

Ejemplo  1.  Generando  y  capturando  un  error 


<?php 

//  Este  ejemplo  contiene  un  error,  que  sera  capturado . 

$ld  =  ldap_connect ( "localhost" ) ; 

$bind  =  ldap_bind ( $ld) ; 

//  error  de  sintaxis  en  la  expresion  del  filtro  (codigo 
//  de  error  87).  Deberia  ser  "ob jectclass=* " . 

$res  =  @ldap_search ($ld,  "o=Mi  Compania,  c=ES",  "ob jectclass" ) ; 
if  ( ! $res)  { 

printf ( "LDAP-Codigo  Error:  %s<br>\n",  ldap_errno ($ld) ) ; 
printf ( "LDAP-Mensaje  Error:  %s<br>\n",  ldap_error ($ld) ) ; 
die ( "Argh ! <br>\n" ) ; 

} 

$info  =  ldap_get_entries ( $ld,  $res) ; 

printf ("%d  entradas  encontradas . <br>\n" ,  $inf o [ "count "]) ; 

?> 


Ver  tambien  Idap_err2str0  y  ldap_error(). 
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LDAP 


Devuelte  el  mensaje  de  error  del  ultimo  comando  LDAP 

string  ldap_error  (int  identificador_de_conexion) 


Devuelve  una  cadena  con  el  mensaje  de  error. 

Esta  funcion  devuelve  una  cadena  con  el  mensaje  de  error  explicativo  del  error  generado  por  el  ultimo 
comando  LDAP  en  la  conexion  especificada.  Aunque  los  codigos  de  error  LDAP  estan  estandarizados, 
diferentes  librerfas  devuelven  mensajes  textuales  de  error  diferentes  o  incluso  localizados.  Nunca  se  debe 
comprobar  la  existencia  de  un  error  especffico  por  el  mensaje  textual,  sino  por  el  codigo  numerico. 

A  menos  que  decremente  el  nivel  de  alerta  en  su  fichero  php3  .  ini  (6  php .  ini)  o  anteponga  a  los 
comandos  LDAP  en  sfmbolo  @  (arroba)  para  suprimir  las  alertas  y  warnings,  los  errores  producidos 
seran  mostrados  automaticamente  en  el  codigo  HTML  generado. 

Ver  tambien  Idap_err2str0  y  Idap  crrno  '). 
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XLIV.  Funciones  de  Correo 


The  mail()  Funciones  que  permiten  enviar  correo. 
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mail 


(PHP  3,  PHP  4  >=  4.0.0) 


Envfa  correo 


bool  mail  (string  para,  string  sobre,  string  mensaje  [,  string 
cabeceras_adicionales] ) 


mail()  envfa  automaticamente  el  mensaje  especificado  en  mens  age  al  destinatario  especificado  en 
para.  Para  especificar  multiples  destinatarios  se  puede  hacer  incluyendo  una  coma  entre  las  direcciones 

en  para. 


Ejemplo  1.  Enviando  correo. 

mail ( "pepito@loquesea . es " ,  "Sobre  este  tema",  "Linea  l\nLinea  2\nLinea  3"); 


Si  se  anadiera  una  cadena  como  cuarto  argumento,  esta  cadena  serfa  enviada  al  final  de  la  cabecera.  Esto 
se  usa  normalmente  para  enviar  cabeceras  extra  en  los  mensajes.  Si  se  desea  enviar  varias  cabeceras  extra 
el  mecanismo  sera  el  mismo  separandolas  una  linea. 


Ejemplo  2.  Enviando  correo  con  varias  cabeceras. 

mail ( "pepitoSloquesea . es " ,  "El  tema",  $message, 

"From:  webmaster® $ SERVER_NAME\nReply— To :  webmaster® $SERVER_NAME\nX— Mailer :  PHP/" 


.  php\ 
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XLV.  Funciones  matematicas 


Introduccion 


Estas  funciones  matematicas  solo  manejan  valores  dentro  de  los  rangos  de  los  tipos  long  y  double  de  su 
ordenador.  Si  necesita  manejar  numeros  mayores,  pege  un  vistazo  a  funciones  matematicas  de  precision 
arbitraria 


Constantes  matematicas 


Los  siguientes  valores  estan  definidos  como  constantes  en  PHP  por  la  extension  matematica: 

Tabla  1.  Constantes  matematicas 


Constante 

Valor 

Description 

M_PI 

3.14159265358979323846 

El  valor  de '][  (pi) 
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abs  (PHP  3,  PHP  4  >=  4.0.0) 


Math. 


Valor  absoluto 

mixed  abs  (mixed  number) 

Devuelve  el  valor  absoluto  de  un  numero.  Si  el  numero  del  argumento  es  decimal,  el  tipo  de  retorno 
tambien  es  decimal,  de  otra  manera  devuelve  un  entero. 

acos  (PHP  3,  PHP  4  >=  4.0.0) 

Arco  coseno 

float  acos  (float  arg) 

Devuelve  el  arco  coseno  de  arg  en  radianes. 

Vea  tambien  asin()  y  atan)). 

asin  (PHP  3,  PHP  4  >=4.0.0) 

Arco  seno 

float  asin  (float  arg) 

Devuelve  el  arco  seno  de  arg  en  radianes. 

Vea  tambien  acos()  y  atan(). 

atari  (PHP  3,  PHP  4  >=  4.0.0) 

Arco  tangente 

float  atan  (float  arg) 
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Devuelve  la  arco  tangente  de  arg  en  radianes. 
Vea  tambien  acos')  y  atan(). 


Math. 


atan2  (PHP  3>=  3.0.5,  PHP  4  >=  4.0.0) 

Arco  tangente  de  dos  variables 

float  atan2  (float  y,  float  x) 

Esta  funcion  calcula  la  arco  tangente  de  las  dos  variables  x  e  y.  Es  similar  a  el  calculo  de  la  arco  tangente 
de  y  /  x,  excepto  que  los  signos  de  ambos  argumentos  son  usados  para  determinar  el  cuadrante  del 
resultado 

La  funcion  devuelve  el  resultado  en  radianes,  el  cual  esta  entre  -PI  y  PI  (inclusive). 

Vea  tambien  acos()  y  atan(). 

base_convert  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 

Convierte  un  numero  entre  bases  arbitrarias 

strin  base_convert  (string  number,  int  frombase ,  int  tobase) 


Devuelve  una  cadena  conteniendo  el  number  representado  en  base  tobase.  La  base  en  la  cual 
number  es  dado  viene  especificada  en  frombase.  Tanto  frombase  y  tobase  tienen  que  estar  entre 
2  y  36,  inclusive.  Los  dfgitos  en  numeros  con  una  base  mayor  que  10  seran  representados  con  las  letras 
a-z,  a  vale  10,  b  vale  1 1  y  z  vale  36. 

Ejemplo  1.  base_convert() 

$binary  =  base_convert ($hexadecimal,  16,  2) ; 


BinDec  (PHP  3,  PHP  4  >=  4.0.0) 


binario  a  decimal 


int  bindec  (string  binary_strlng) 
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Devuelve  el  equivalente  decimal  del  numero  binario  representado  por  el  argumento  binary _string. 

BinDec  convierte  un  numero  binario  en  un  numero  decimal.  El  mayor  numero  que  puede  ser  convertido 
son  31  bits  de  unos  o  2147483647  en  decimal. 

Vea  tambien  la  funcion  decbin ')  . 


ceil  (PHP  3,  PHP  4  >=  4.0.0) 

Redondea  fracciones  hacia  arriba 


int  ceil  (float  number) 


Devuelve  el  valor  entero  superior  mas  cercano  a  number.  El  uso  de  ceil()  con  enteros  es  una  perdida  de 
tiempo  absoluta. 

NOTA:  PHP/FI  2’s  ceil()  devuelve  un  float.  Use:  $new  =  (double)  ceil  ($number)  ;  para  tener  el 
comportamiento  antiguo. 

Vea  tambien  floor  )  y  round )). 


COS  (PHP  3,  PHP  4  >=4.0.0) 
coseno 

float  cos  (float  arg) 

Devuelve  el  coseno  de  arg  en  radianes. 
Vea  tambien  sin))  y  tan)). 

DecBin  (PHP  3,  PHP  4  >=  4.0.0) 

decimal  a  binario 

string  decbin  (int  number) 
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Devuelve  una  cadena  conteniendo  la  representation  en  binario  de  el  numero  dado  en  el  argumento.  El 
numero  mayor  que  puede  ser  convertido  es  2147483647  en  decimal  que  resulta  una  cadena  de  31  unos. 

Vea  tambien  la  funcion  bindec ')  . 


DecHex  (PHP  3,  PHP  4  >=  4.0.0) 

decimal  a  hexadecimal 

string  dechex  (int  number) 

Devuelve  una  cadena  conteniendo  la  representation  hexadecimal  del  numero  dado  en  el  argumento.  El 
mayor  numero  que  puede  ser  convertido  es  2147483647  en  decimal  resultando  "7fffffff '. 

Vea  tambien  la  funcion  hexdec ') . 


DecOct  (PHP  3,  PHP  4  >=  4.0.0) 


decimal  a  octal 


string  decoct  (int  number) 


Devuelve  una  cadena  conteniendo  la  representation  octal  del  numero  dado  en  el  argumento.  Returns  a 
string  containing  an  octal  representation  of  the  given  number  argument.  El  mayor  numero  que  puede  ser 
ocnvertido  es  2147483647  en  decimal  resultando  "17777777777".  Vea  tambien  octdec )). 


exp  (PHP  3,  PHP  4  >=  4.0.0) 
e  elevado  a... 

float  exp  (float  arg) 

Devuelve  el  numero  e  elevado  a  la  potencia  de  arg. 
Vea  tambien  pow  (). 
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redondea  fracciones  hacia  abajo 


int  floor  (float  number) 


Devuelve  el  valor  entero  inferior  mas  cercano  a  number.  El  uso  de  floor()  con  enteros  es  una  perdida  de 
tiempo  absoluta. 

NOTA:  PHP/FI  2’s  floor()  devuelve  un  float.  Use:  $new  =  (double)  floor  ($number)  ;  para  tener  el 
comportamiento  antiguo. 

Vea  tambien  ceil))  y  round  )). 


getrandmax  (php 3,  php 4 >=  4 0  0) 

Muestra  el  mayor  valor  aleatorio  posible 

int  getrandmax  (void) 


Devuelve  el  valor  maximo  que  puede  devolver  una  llamada  a  rand)). 
Vea  tambien  rand)),  srand))  mt_rand  ),  mt_srand))  y  mt_getrandmax')- 


HexDec  (PHP  3,  PHP  4  >=  4.0.0) 


hexadecimal  a  decimal 


int  hexdec  (string  hex_string) 


Devuelve  el  equivalente  decimal  de  el  numero  hexadecimal  representado  por  el  argumento  hex_string. 
HexDec  convierte  una  cadena  hexadecimal  en  un  numero  decimal.  El  numero  mayor  que  puede  ser 
convertido  es  7fffffff  o  2147483647  en  decimal. 

Vea  tambien  la  funcion  dechex )) . 
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Logaritmo  natural 

float  log  (float  arg ) 

Devuelve  el  logaritmo  de  arg. 


loglO  (PHP  3,  PHP  4  >=  4.0.0) 

Logaritmo  en  base- 10 

float  loglO  (float  arg) 

Devuelve  el  logaritmo  en  base- 10  de  arg. 


max  (PHP  3,  PHP  4  >=4.0.0) 

encuentra  el  valor  mayor 

mixed  max  (mixed  argl,  mixed  arg2,  mixed  argn) 

max()  devuelve  el  numero  mayor  de  los  valores  de  los  parametros. 

Si  el  primer  parametro  es  un  array,  max()  devuelve  el  mayor  valor  en  ese  array.  Si  el  primer  parametro  es 
un  entero,  string  o  double,  necesita  al  menos  dos  parametros  y  max()  devuelve  el  mayor  numero  de  estos 
valores.  Puede  comparar  un  numero  ilimitado  de  valores. 

Si  uno  o  mas  de  los  valores  es  un  double,  todos  los  valores  seran  tratados  como  doubles,  y  devolvera  un 
double.  Si  ninguno  de  los  valores  es  un  double,  todos  ellos  seran  tratados  como  enteros,  y  se  devolvera 
un  entero. 


min  (PHP  3,  PHP  4  >=4.0.0) 

encuentra  el  valor  menor 
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mixed  min  (mixed  argl,  mixed  arg2,  mixed  argn) 


min()  returns  the  numerically  lowest  of  the  parameter  values. 

Si  el  primer  parametro  es  un  array,  min()  devuelve  el  menor  valor  en  ese  array.  Si  el  primer  parametro  es 
un  entero,  string  o  double,  necesita  al  menos  dos  parametros  y  min()  devuelve  el  numero  menor  de  estos 
valores.  Puede  comparar  un  numero  ilimitado  de  valores. 

Si  uno  o  mas  de  los  valores  es  un  double,  todos  los  valores  seran  tratados  como  doubles,  y  devolvera  un 
double.  Si  ninguno  de  los  valores  es  un  double,  todos  ellos  seran  tratados  como  enteros,  y  se  devolvera 
un  entero. 


mt_rand  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 
genera  un  valor  aleatorio  mejorado 

int  mt_rand  (  [int  min  [,  int  max] ] ) 


Muchos  generadores  de  numeros  aleatorios  de  libcs  antiguas  tienen  caracterfsticas  dudosas  o 
desconocidas  y  son  lentas.  Por  defecto,  PHP  usa  el  generador  de  numeros  aleatorios  de  libc  con  la 
funcion  rand').  La  funcion  mt_rand()  es  un  reemplazo  para  esta.  Usa  un  generador  de  numeros 
aleatorios  con  caracterfsticas  conocidas,  el  Tornado  de  Mersenne,  que  es  capaz  de  producir  numeros 
aleatorios  que  incluso  se  pueden  emplear  para  propositos  criptograficos  y  es  cuatro  veces  mas  rapido  que 
la  media  de  los  que  provee  libc.  La  pagina  principal  del  Tornado  de  Mersenne  puede  encontrarse  en 
http://www.math.keio.ac.jp/~matumoto/emt.html,  y  una  version  optimizada  del  codigo  del  TM  esta 
disponible  en  http://www.scp.syr.edu/~marc/hawk/twister.html. 

Si  es  llamada  sin  los  parametros  opcionales  min  y  max  mt_rand()  devuelve  un  valor  pseudo-aleatorio 
entre  0  y  RAND_MAX.  Si  quiere  un  numero  aleatorio  entre  5  y  15  (inclusive),  use  mt_rand(5,15). 

Recuerde  introducir  la  semilla  del  generador  de  numeros  aleatorios  antes  de  usar  la  instruction  con 
mt_srand(). 

Vea  tambien  mt_srand )),  mt_getrandmax )),  srand '),  rand  ))  y  getrandmax '). 


mt_srand  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 

Introduce  la  semilla  del  generador  de  numeros  aleatorios  mejorado 

void  mt_srand  (int  seed) 


Introduce  la  semilla  seed  en  el  generador  de  numeros  aleatorios  mejorado. 
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//  seed  son  los  microsegundos  desde  el  ultimo  segundo  "entero" 
mt_srand ( (double) micro time () *1000000) ; 

$randval  =  mt_rand ( ) ; 


Vea  tambien  mtrand'),  mt_getrandmax '),  srand'),  rand  ')  y  getrandmax'). 


mt_getrandmax  (php  3>=  3.0.6,  php  4  >=  4.o.0) 

muestra  el  mayor  valor  aleatorio  posible 

int  mt_getrandmax  (void) 

Devuelve  el  valor  maximo  que  se  puede  obtener  con  una  llamada  a  mt  rand  '). 
Vea  tambien  mt  rand  ).  mtsrand)  rand'),  srand  )  y  getrandmax '). 


number  format  (phps,  php 4>=4.o.o) 


formatea  un  numero  en  grupos  de  miles 


string  number_format  (float  number,  int  decimals ,  string  dec_point ,  string 
thousands_sep) 


number_format()  devuelve  la  version  formateada  de  number.  Esta  funcion  acepta  tanto  uno,  como  dos 
o  cuatro  parametros  (tres  no): 

Si  solo  se  da  un  parametro,  number  sera  formateado  sin  decimales,  pero  con  una  coma  (",")  entre  cada 
grupo  de  miles. 

Si  se  dan  dos  parametros,  number  sera  formateado  con  decimals  decimales  con  un  punto  (".")  al 
principio,  y  una  coma  (",")  entre  cada  grupo  de  miles. 

Si  se  dan  cuatro  parametros,  number  sera  formateado  con  decimals  decimales,  dec_point  en  vez 
del  punto  (".")  antes  de  los  decimales  y  thousands_sep  en  vez  de  la  coma  (",")  entre  cada  grupo  de 
miles. 
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OctDec  (PHP  3,  PHP  4  >=  4.0.0) 

octal  a  decimal 

int  octdec  (string  octal_string) 

Devuelve  el  equivalente  decimal  del  numero  octal  representado  por  el  argumento  octal_string.  OctDec 
convierte  una  cadena  octal  en  un  numero  decimal.  El  mayor  numero  que  puede  ser  convertido  es 
17777777777  o  2147483647  en  decimal. 

Vea  tambien  decoct '). 

Pi  (PHP  3,  PHP  4  >=4.0.0) 

devuelve  el  valor  de  pi 

double  pi  (void) 

Devuelve  una  aproximacion  de  pi. 

pow  (PHP  3,  PHP  4  >=  4.0.0) 
expresion  exponencial 

float  pow  (float  base,  float  exp) 

Devuelve  base  elevado  a  la  potencia  de  exp. 

Vea  tambien  exp  3. 

rand  (PHP  3,  PHP  4  >=  4.0.0) 

genera  un  valor  aleatorio 

int  rand  ([int  min  [,  int  max]]) 
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Si  es  llamada  sin  los  argumentos  opcionales  min  y  max,  rand()  devuelve  un  valor  pseudo-aleatorio  entre 
0  y  RAND_MAX.  Si  quiere  un  numero  aleatorio  entre  5  y  15  (inclusive),  por  ejemplo,  use  rand(5,15). 

Recuerde  introducir  la  semilla  del  generador  de  numeros  aleatorios  antes  de  usar  srand'). 

Vea  tambien  srand  '),  getrandmax)),  mt  rand  ),  mt_srand\)  y  mt_getrandmax  ')- 


round  (PHP  3,  PHP  4  >=  4.0.0) 


Redondea  un  float. 


double  round  (double  val) 


Devuelve  el  valor  redondeado  de  val. 


$foo  = 

round ( 

3.4  )  ; 

// 

$foo  == 

3.0 

$foo  = 

round ( 

3.5  )  ; 

// 

$foo  == 

4.0 

$foo  = 

round ( 

3.6  )  ; 

// 

$foo  == 

4.0 

Vea  tambien  ceil')  y  floor  3. 


sin  (PHP  3,  PHP  4  >=4.0.0) 

seno 

float  sin  (float  arg) 

Devuelve  el  seno  de  arg  en  radianes. 
Vea  tambien  cos 3  y  tan)). 

sqrt  (PHP  3,  PHP  4  >=4.0.0) 

Ra(z  cuadrada 

float  sqrt  (float  arg) 
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Devuelve  la  rafz  cuadrada  de  arg. 


srand  (PHP  3,  PHP  4  >=  4.0.0) 

introduce  la  semilla  del  generador  de  numeros  aleatorios 

void  srand  (int  seed) 


Inicializa  el  generador  de  numeros  aleatorios  con  seed. 

//  seed  son  los  microsegundos  desde  el  ultimo  segundo  "entero" 
srand ( (double ) microtime () *1000000) ; 

$randval  =  rand ( ) ; 


Vea  tambien  rand  '),  getrandmax)),  mt  rand '),  mt_srand ')  y  mt_getrandmax '). 

tan  (PHP  3,  PHP  4  >=4.0.0) 
tangente 

float  tan  (float  arg) 

Devuelve  la  tangente  de  arg  en  radianes. 

Vea  tambien  sin ')  y  cos))- 
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Aviso 

This  module  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  these 
functions,  these  function  names,  in  concreto  ANYTHING  documented  here  can 
change  in  a  future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this 
module  at  your  own  risk. 


Introduction 


Aviso 

This  module  is  EXPERIMENTAL.  Function  name/API  is  subject  to  change.  Current 
conversion  filter  supports  Japanese  only. 


There  are  many  languages  in  which  all  characters  can  be  expressed  by  single  byte.  Multi-byte  character 
codes  are  used  to  express  many  characters  for  many  languages,  mbstring  is  developed  to  handle 
Japanese  characters.  However,  many  mbstring  functions  are  able  to  handle  character  encoding  other 
than  Japanese. 

A  multi -byte  character  encoding  represents  single  character  with  consecutive  bytes.  Some  character 
encoding  has  shift(escape)  sequences  to  start/end  multi -byte  character  strings.  Therefore,  a  multi-byte 
character  string  may  be  destroyed  when  it  is  divided  and/or  counted  unless  multi-byte  character  encoding 
safe  method  is  used.  This  module  provides  multi-byte  character  safe  string  functions  and  other  utility 
functions  such  as  conversion  functions. 

Since  PHP  is  basically  designed  for  ISO-8859- 1,  some  multi-byte  character  encoding  does  not  work  well 
with  PHP.  Therefore,  it  is  important  to  set  mbstring .  internal_encoding  to  a  character  encoding 
that  works  with  PHP. 

PHP4  Character  Encoding  Requirements 


•  Per  byte  encoding 

•  Single  byte  characters  in  range  of  0 0h-7fh  which  is  compatible  with  ascii 

•  Multi-byte  characters  without  00h-7fh 


These  are  examples  of  internal  character  encoding  that  works  with  PHP  and  does  NOT  work  with  PHP. 


Character  encodings 
ISO-8859-*,  EUC-JP, 


Character  encodings 
JIS,  SJIS 


work  with  PHP : 
UTF-8 


do  NOT  work  with  PHP : 
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Character  encoding,  that  does  not  work  with  PHP,  may  be  converted  with  mbstring’s  HTTP 
input/output  conversion  feature/function. 

Nota:  SJIS  should  not  be  used  for  internal  encoding  unless  the  reader  is  familiar  with 
parser/compiler,  character  encoding  and  character  encoding  issues. 


Nota:  If  you  use  database  with  PHP,  it  is  recommended  that  you  use  the  same  character  encoding 
for  both  database  and  internal  encoding  for  ease  of  use  and  better  performance. 

If  you  are  using  PostgreSQL,  it  supports  character  encoding  that  is  different  from  backend  character 
encoding.  See  the  PostgreSQL  manual  for  details. 


How  to  Enable  mbstring 

mbstring  is  an  extended  module.  You  must  enable  module  with  configure  script.  Refer  to  the  Install 
section  for  details. 

The  following  configure  options  are  related  to  mbstring  module. 


•  — enable-mbstring  :  Enable  mbstring  functions.  This  option  is  required  to  use  mbstring 
functions. 

•  — enable-mbstr-enc-trans  :  Enable  HTTP  input  character  encoding  conversion  using 
mbstring  conversion  engine.  If  this  feature  is  enabled,  HTTP  input  character  encoding  may  be 
converted  to  mbstring  .  internal_encoding  automatically. 


HTTP  Input  and  Output 

HTTP  input/output  character  encoding  conversion  may  convert  binary  data  also.  Users  are  supposed  to 
control  character  encoding  conversion  if  binary  data  is  used  for  HTTP  input/output. 

If  enctype  for  HTML  form  is  set  to  multipart/form-data,  mbstring  does  not  convert  character 
encoding  in  POST  data.  If  it  is  the  case,  strings  are  needed  to  be  converted  to  internal  character  encoding. 


•  HTTP  Input 

There  is  no  way  to  control  HTTP  input  character  conversion  from  PHP  script.  To  disable  HTTP  input 
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character  conversion,  it  has  to  be  done  in  php .  ini. 

Ejemplo  1.  Disable  HTTP  input  conversion  in  php.ini 


; ;  Disable  HTTP  Input  conversion 
mbstring . http_input  =  pass 


When  using  PHP  as  an  Apache  module,  it  is  possible  to  override  PHP  ini  setting  per  Virtual  Host  in 
httpd.conf  or  per  directory  with  .htaccess.  Refer  to  the  Configuration  section  and  Apache 
Manual  for  details. 

•  HTTP  Output 

There  are  several  ways  to  enable  output  character  encoding  conversion.  One  is  using  php .  ini, 
another  is  using  ob_start  )  with  m b_ou tp u t_h an d I e r )  as  ob_start  callback  function. 

Nota:  For  PHP3-i18n  users,  mbstring’s  output  conversion  differs  from  PHP3-i18n.  Character 
encoding  is  converted  using  output  buffer. 


Ejemplo  2.  php .  ini  setting  example 

; ;  Enable  output  character  encoding  conversion  for  all  PHP  pages 

; ;  Enable  Output  Buffering 
output_buf fering  =  On 

; ;  Set  mb_output_handler  to  enable  output  conversion 
output_handler  =  mb_output_handler 


Ejemplo  3.  Script  example 

<?php 

//  Enable  output  character  encoding  conversion  only  for  this  page 

//  Set  HTTP  output  character  encoding  to  SJIS 
mb_http_output ('SOTS'  )  ; 
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//  Start  buffering  and  specify  "mb_output_handler "  as 

/ /  callback  function 

ob_start ( ' mb_output_handler ' ) ; 

?> 


Supported  Character  Encoding 

Currently,  the  following  character  encoding  is  supported  by  mbstring  module.  Caracter  encoding  may 
be  specified  for  mbstring  functions’  encoding  parameter. 

The  following  character  encoding  is  supported  in  this  PHP  extension  : 

UCS-4, UCS-4BE,  UCS-4LE,  UCS-2,  UCS-2BE,  UCS-2LE,  UTF-32,  UTF-32BE,  UTF-32LE,  UCS-2LE, 
UTF-16,  UTF-16BE, UTF-16LE, UTF-8,  UTF-7,  ASCII,  EUC-JP,  SJIS,  eucJP-win,  SJIS-win, 
ISO-2022- JP,  JIS,  ISO-8859-1,  ISO-8859-2,  ISO-8859-3,  ISO-8859-4,  ISO-8859-5, 
ISO-8859-6,  ISO-8859-7,  ISO-8859-8,  ISO-8859-9,  ISO-8859-10,  ISO-8859-13, 
ISO-8859-14,  ISO-8859-15,  byte2be,  byte21e,  byte4be,  byte41e,  BASE64,  7bit,  8bit  and 
UTF7-IMAP. 

php .  ini  entry,  which  accepts  encoding  name,  accepts  "auto"  and  "pass"  also,  mbstring  functions, 
which  accepts  encoding  name,  and  accepts  "auto". 

If  "pass"  is  set,  no  character  encoding  conversion  is  performed. 

If  "auto"  is  set,  it  is  expanded  to  "ascii,  jis,  utf-8,  euc-jp,  sjis". 

See  also  mb_detect_order') 

Nota:  "Supported  character  encoding"  does  not  mean  that  it  works  as  internal  character  code. 


php. ini  settings 

•  mbstring .  internal_encoding  defines  default  internal  character  encoding. 

•  mbstring .  http_input  defines  default  HTTP  input  character  encoding. 

•  mbstring .  http_output  defines  default  HTTP  output  character  encoding. 

•  mbstring .  detect_order  defines  default  character  code  detection  order.  See  also 
mb_detect_order'). 

•  mbstring .  substitute_character  defines  character  to  substitute  for  invalid  character  encoding. 

Web  Browsers  are  supposed  to  use  the  same  character  encoding  when  submitting  form.  However, 
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browsers  may  not  use  the  same  character  encoding.  See  mb_http_input [)  to  detect  character  encoding 
used  by  browsers. 

If  enctype  is  set  to  multipart/form-data  in  HTML  forms,  mbstring  does  not  convert  character 
encoding  in  POST  data.  The  user  must  convert  them  in  the  script,  if  conversion  is  needed. 

Although,  browsers  are  smart  enough  to  detect  character  encoding  in  HTML,  charset  is  better  to  be  set 
in  HTTP  header.  Change  default_charset  according  to  character  encoding. 


Ejemplo  4.  php .  ini  setting  example 


; ;  Set  default  internal  encoding 

;;  Note:  Make  sure  to  use  character  encoding  works  with  PHP 

mbstring . internal_encoding  =  UTF-8  ;  Set  internal  encoding  to  UTF-8 


; ;  Set  default  HTTP  input  character  encoding 
;;  Note:  Script  cannot  change  http_input  setting, 
mbstring . http_input  =  pass  ;  No  conversion, 

mbstring . http_input  =  auto  ;  Set  HTTP  input  to  auto 

;  "auto"  is  expanded  to  "ASCI I , JIS, UTF-8 , EUC-JP, SJIS " 
mbstring . http_input  =  SJIS  ;  Set  HTTP2  input  to  SJIS 

mbstring . http_input  =  UTF-8, SJIS, EUC-JP  ;  Specify  order 


; ;  Set  default  HTTP  output  character  encoding 
mbstring . http_output  =  pass  ;  No  conversion 

mbstring . http_output  =  UTF-8  ;  Set  HTTP  output  encoding  to  UTF-8 

; ;  Set  default  character  encoding  detection  order 

mbstring . detect_order  =  auto  ;  Set  detect  order  to  auto 

mbstring . detect_order  =  ASCII, JIS, UTF-8, SJIS, EUC-JP  ;  Specify  order 

; ;  Set  default  substitute  character 

mbstring . substitute_character  =  12307  ;  Specify  Unicode  value 

mbstring . substitute_character  =  none  ;  Do  not  print  character 

mbstring . substitute_character  =  long  ;  Long  Example:  U+3000, JIS+7E7E 


Ejemplo  5.  php .  ini  setting  for  euc-jp  users 


; ;  Disable  Output  Buffering 
output_buf f ering  =  Off 

; ;  Set  HTTP  header  charset 
def ault_charset  =  EUC-JP 

; ;  Set  HTTP  input  encoding  conversion  to  auto 
mbstring . http_input  =  auto 
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; ;  Convert  HTTP  output  to  EUC-JP 
mbstring . http_output  =  EUC-JP 

; ;  Set  internal  encoding  to  EUC-JP 
mbstring . internal_encoding  =  EUC-JP 

; ;  Do  not  print  invalid  characters 
mbstring . substitute_character  =  none 


Ejemplo  6.  php .  ini  setting  for  s  jis  users 


; ;  Enable  Output  Buffering 
output_buf f ering  =  On 

; ;  Set  mb_output_handler  to  enable  output  conversion 
output_handler  =  mb_output_handler 

; ;  Set  HTTP  header  charset 

def ault_charset  =  Shift_JIS 

; ;  Set  http  input  encoding  conversion  to  auto 
mbstring . http_input  =  auto 

; ;  Convert  to  SJIS 
mbstring . http_output  =  SJIS 

; ;  Set  internal  encoding  to  EUC-JP 
mbstring . internal_encoding  =  EUC-JP 

; ;  Do  not  print  invalid  characters 
mbstring . substitute_character  =  none 


Basics  for  Japanese  multi-byte  character 

Most  Japanese  characters  need  more  than  1  byte  per  character.  In  addition,  several  character  encoding 
schemas  are  used  under  a  Japanese  environment.  There  are  EUC-JP,  Shift_JIS(SJIS)  and 
ISO-2022-JP(JIS)  character  encoding.  As  Unicode  becomes  popular,  UTF-8  is  used  also.  To  develop 
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Web  applications  for  a  Japanese  environment,  it  is  important  to  use  the  character  set  for  the  task  in  hand, 
whether  HTTP  input/output,  RDBMS  and  E-mail. 


•  Storage  for  a  character  can  be  up  to  four  bytes 

•  A  multi-byte  character  is  usually  twice  of  the  width  compared  to  single-byte  characters.  Wider 
characters  are  called  "zen-kaku"  -  meaning  full  width,  narrower  characters  are  called  "han-kaku"  - 
meaning  half  width,  "zen-kaku"  characters  are  usually  fixed  width. 

•  Some  character  encoding  defines  shift(escape)  sequence  for  entering/exiting  multi-byte  character 
strings. 

•  ISO-2022-JP  must  be  used  for  SMTP/NNTP. 

•  "i-mode"  web  site  is  supposed  to  use  SJIS. 


References 

Multi-byte  character  encoding  and  its  related  issues  are  very  complex.  It  is  impossible  to  cover  in 
sufficient  detail  here.  Please  refer  to  the  following  URLs  and  other  resources  for  further  readings. 

•  Unicode/UTF/UCS/etc 

http : / / www . Unicode . org/ 

•  Japanese/Korean/Chinese  character  information 

ftp://ftp.ora. com/pub/ examples /nut shell/u j ip/doc/c jk .inf 
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mb  Janguage  (php  4  >=  4.0.6) 


Set/Get  current  language 


string  mb_language  ( [string  language ] ) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


mb_language()  sets  language.  If  language  is  omitted,  it  returns  current  language  as  string. 

language  setting  is  used  for  encoding  e-mail  messages.  Valid  languages  are  "Japanese", 

"ja", "English", "en"  and  "uni"  (UTF-8).  mb_send_mail ')  uses  this  setting  to  encode  e-mail. 

Language  and  its  setting  is  ISO-2022-JP/Base64  for  Japanese,  UTF-8/Base64  for  uni, 

ISO-8859- 1/quoted  printable  for  English. 

Return  Value:  If  language  is  set  and  language  is  valid,  it  returns  true.  Otherwise,  it  returns  false. 
When  language  is  omitted,  it  returns  language  name  as  string.  If  no  language  is  set  previously,  it 
returns  false. 

See  also  mb_send_mail  '). 


mb_parse_str  (php  4  >=  4 .0 .6> 


Parse  GET/POST/COOKIE  data  and  set  global  variable 


string  mb_parse_str  (string  encoded_string  [,  array  result ]) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


mb_parse_str()  parses  GET/POST/COOKIE  data  and  sets  global  variables.  Since  PHP  does  not  provide 
raw  POST/COOKIE  data,  it  can  only  used  for  GET  data  for  now.  It  preses  URL  encoded  data,  detects 
encoding,  converts  coding  to  internal  encoding  and  set  values  to  result  array  or  global  variables. 

encoded_string :  URL  encoded  data. 
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result :  Array  contains  decoded  and  character  encoding  converted  values. 
Return  Value:  It  returns  true  for  success  or  false  for  failure. 

See  also  mb_detect_order'),  mb  internal  encoding'j. 


mb  Jnternal_encoding  (php  4  >=  4.0.6) 


Set/Get  internal  character  encoding 


string  mb_internal_encoding  ([string  encoding ]) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


mb_internal_encoding()  sets  internal  character  encoding  to  encoding  If  parameter  is  omitted,  it 
returns  current  internal  encoding. 

encoding  is  used  for  HTTP  input  character  encoding  conversion,  HTTP  output  character  encoding 
conversion  and  default  character  encoding  for  string  functions  defined  by  mbstring  module. 

encoding:  Character  encoding  name 

Return  Value:  If  encoding  is  set,mb_internal_encoding()  returns  true  for  success,  otherwise  returns 
false.  If  encoding  is  omitted,  it  returns  current  character  encoding  name. 


Ejemplo  1.  mb_internal_encoding()  example 

/*  Set  internal  character  encoding  to  UTF-8  */ 
mb_internal_encoding ( "UTF-8 " )  ; 

/*  Display  current  internal  character  encoding  */ 
echo  mb_internal_encoding ( ) ; 


See  also  mb_http_input[),  mb_http_output(),  mb_dctect_order'). 


mb_http  Jnput  (php  4  >=  4  0  6) 


Detect  HTTP  input  character  encoding 
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string  mb_http_input  ( [string  type ] ) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


mb_http_input()  returns  result  of  HTTP  input  character  encoding  detection. 

type :  Input  string  specifies  input  type.  "G"  for  GET,  "P"  for  POST,  "C"  for  COOKIE.  If  type  is  omitted, 
it  returns  last  input  type  processed. 

Return  Value:  Character  encoding  name.  If  mb_http_input()  does  not  process  specified  HTTP  input,  it 
returns  false. 

See  also  mb_internal_encoding  [),  mb_http_outputO,  mb_detect_order'). 


mb_http_output  (php  4  >=  4  0  6) 


Set/Get  HTTP  output  character  encoding 


string  mb_http_output  ([string  encoding ]) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


If  encoding  is  set,  mb_http_output()  sets  HTTP  output  character  encoding  to  encoding.  Output 
after  this  function  is  converted  to  encoding.  mb_http_output()  returns  true  for  success  and  false 
for  failure. 

If  encoding  is  omitted,  mb_http_output()  returns  current  HTTP  output  character  encoding. 

See  also  mb_internal_encoding  (),  mb_http_input'),  mb_detect_order(). 


mb_detect_order  (php  4  >=  4  o  6> 


Set/Get  character  encoding  detection  order 
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array  mb_detect_order  ([mixed  encoding-list ]) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


mb_detect_order()  sets  automatic  character  encoding  detection  order  to  encoding-list.  It  returns 
true  for  success,  false  for  failure. 

encoding-list  is  array  or  comma  separated  list  of  character  encoding,  ("auto"  is  expanded  to 
"ASCII,  JIS,  UTF-8,  EUC-JP,  SJIS") 

If  encoding-list  is  omitted,  it  returns  current  character  encoding  detection  order  as  array. 

This  setting  affects  mb_detect_encoding ')  and  mb_send_mail  ')• 

Nota:  mbstring  currently  implements  following  encoding  detection  filters.  If  there  is  a  invalid  byte 
sequence  for  following  encoding,  encoding  detection  will  fail. 

Nota:  UTF-8,  UTF-7,  ASCII,  EUC-JP, SJIS,  eucJP-win,  S JlS-win,  JIS,  ISO-2022-JP 
For  ISO-8859-*,  mbstring  always  detects  as  ISO-8859-*. 

For  utf-16,  utf-32,  ucs2  and  ucs4,  encoding  detection  will  fail  always. 


Ejemplo  1.  Useless  detect  order  example 

;  Always  detect  as  ISO-8859-1 
detect_order  =  ISO-8859-1,  UTF-8 

;  Always  detect  as  UTF-8,  since  ASCII/UTF-7  values  are 
;  valid  for  UTF-8 

detect_order  =  UTF-8,  ASCII,  UTF-7 


Ejemplo  2.  mb_detect_order()  examples 

/*  Set  detection  order  by  enumerated  list  */ 
mb_detect_order ( "euc jp-win,  s jis-win,  UTF-8" )  ; 

/*  Set  detection  order  by  array  */ 

$ary  [  ]  =  "ASCII"; 

$ary [ ]  =  "JIS"; 

$ary [ ]  =  "EUC-JP"; 
mb_detect_order ($ary) ; 
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/*  Display  current  detection  order  */ 
echo  implode (",  ",  mb_detect_order ( ) ) ; 


See  also  mb_internal_encoding '),  mb_http_input'),  mb_http_output')  mb_send_mail '). 


mb_substitute_character  (php  4  >=  4.0.6) 


Set/Get  substitution  character 


mixed  mb_substitute_character  ( [mixed  substrchar] ) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


mb_substitute_character()  specifies  substitution  character  when  input  character  encoding  is  invalid  or 
character  code  is  not  exist  in  output  character  encoding.  Invalid  characters  may  be  substituted  NULLfno 
output),  string  or  integer  value  (Unicode  character  code  value). 

This  setting  affects  mb_detect_encoding ')  and  mb_send_mail '). 

substchar  :  Specify  Unicode  value  as  integer  or  specify  as  string  as  follows 


•  "none"  :  no  output 

•  "long"  :  Output  character  code  value  (Example:  U+3000JIS+7E7E) 


Return  Value:  If  substchar  is  set,  it  returns  true  for  success,  otherwise  returns  false.  If 
substchar  is  not  set,  it  returns  Unicode  value  or  "none"/"long". 

Ejemplo  1.  mb_substitute_character()  example 

/*  Set  with  Unicode  U+3013  (GETA  MARK)  */ 
mb_subst itute_character (0x3013)  ; 

/*  Set  hex  format  */ 
mb_substitute_character ( "long" )  ; 

/*  Display  current  setting  */ 
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echo  mb_substitute_character ( )  ; 


mb_output_handler  (php  4  >=  4  o  6> 

Callback  function  converts  character  encoding  in  output  buffer 

string  mb_output_handler  (string  contents ,  int  status) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


mb_output_handler()  is  ob_start')  callback  function.  mb_output_handler()  converts  characters  in 
output  buffer  from  internal  character  encoding  to  HTTP  output  character  encoding. 

4. 1 .0  or  later  version,  this  hanlder  adds  charset  HTTP  header  when  following  conditions  are  met: 


•  Does  not  set  Content-Type  by  header() 

•  Default  MIME  type  begins  with  text/ 

•  http_output  setting  is  other  than  pass 


contents  :  Output  buffer  contents 
status  :  Output  buffer  status 
Return  Value:  String  converted 


Ejemplo  1.  mb_output_handler()  example 


mb_http_output ("UTF-8")  ; 
ob_start ( "mb_output_handler " ) ; 


Nota:  If  you  want  to  output  some  binary  data  such  as  image  from  PHP  script,  you  must  set  output 
encoding  to  "pass"  using  mb_http_output[). 
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See  also  ob_start'). 


mb_preferred_mime_name  (php  4  >=  4.0.6) 


Get  MIME  charset  string 


string  mb_preferred_mime_name  (string  encoding) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


mb_preferred_mime_name()  returns  MIME  charset  string  for  character  encoding  encoding.  It 
returns  charset  string. 


Ejemplo  1.  mb_preferred_mime_string()  example 

$outputenc  =  "sjis-win"; 
mb_http_output ($outputenc) ; 
ob_start ( "mb_output_handler " ) ; 

header ( "Content-Type :  text/html;  charset="  .  mb_preferred_mime_name ( $outputenc) ) 


mb_strleri(PHP4>=4  0  6) 


Get  string  length 


string  mb_strlen  (string  str  |,  string  encoding ]) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 
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mb_strlen()  returns  number  of  characters  in  string  str  having  character  encoding  encoding.  A 
multi-byte  character  is  counted  as  1 . 

encoding  is  character  encoding  for  str.  If  encoding  is  omitted,  internal  character  encoding  is  used. 
See  also  mb_internal_encoding  '),  strlen '). 


mb_strpoS(PHP4>=4  0  6) 


Find  position  of  first  occurrence  of  string  in  a  string 


int  mb_strpos  (string  haystack,  string  needle  [,  int  offset  [,  string 
encoding ] ] ) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


mb_strpos()  returns  the  numeric  position  of  the  first  occurrence  of  needle  in  the  haystack  string.  If 
needle  is  not  found,  it  returns  false. 

mb_strpos()  performs  multi -byte  safe  strpos')  operation  based  on  number  of  characters,  needle 
position  is  counted  from  the  beginning  of  the  haystack.  First  character’s  position  is  0.  Second 
character  position  is  1,  and  so  on. 

If  encoding  is  omitted,  internal  character  encoding  is  used.  mb_strrposO  accepts  string  for  needle 
where  strrpos ')  accepts  only  character. 

offset  is  search  offset.  If  it  is  not  specified,  0  is  used. 

encoding  is  character  encoding  name.  If  it  is  omitted,  internal  character  encoding  is  used. 

See  also  mb_strpos(),  mb_internal_encoding  3,  strpos') 


mb_strrpos  (php  4  >=  4.0.6) 

Find  position  of  last  occurrence  of  a  string  in  a  string 

int  mb_strrpos  (string  haystack,  string  needle  [,  string  encoding]) 
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Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


mb_strrpos()  returns  the  numeric  position  of  the  last  occurrence  of  needle  in  the  haystack  string.  If 
needle  is  not  found,  it  returns  false. 

mb_strrpos()  performs  multi-byte  safe  strrpos  ')  operation  based  on  number  of  characters,  needle 
position  is  counted  from  the  beginning  of  haystack.  First  character’s  position  is  0.  Second  character 
position  is  1 . 

If  encoding  is  omitted,  internal  encoding  is  assumed.  mb_strrpos()  accepts  string  for  needle 
where  strrpos  ')  accepts  only  character. 

encoding  is  character  encoding.  If  it  is  not  specified,  internal  character  encoding  is  used. 

See  also  mb_strpos'),  mb_intcrnal_encoding '),  strrpos'). 


mb_substr(PHP4>=4  0  6) 


Get  part  of  string 


string  mb_substr  (string  str,  int  start  [,  int  length  [,  string  encoding]]) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


mb_substr()  returns  the  portion  of  str  specified  by  the  start  and  length  parameters. 

mb_substr()  performs  multi -byte  safe  suhstr)  operation  based  on  number  of  characters.  Position  is 
counted  from  the  beginning  of  str.  First  character’s  position  is  0.  Second  character  position  is  1,  and  so 
on. 

If  encoding  is  omitted,  internal  encoding  is  assumed. 

encoding  is  character  encoding.  If  it  is  omitted,  internal  character  encoding  is  used. 

See  also  mb_strcutO,  m h  i  n te rn a l_e u c od  i  ng  ' ) . 
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mb_strcut(PHP4>=4  0  6) 


Get  part  of  string 


string  mb_strcut  (string  str,  int  start  [,  int  length  [,  string  encoding]]) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


mb_strcut()  returns  the  portion  of  str  specified  by  the  start  and  length  parameters. 

mb_strcut()  performs  equivalent  operation  as  mb_substr')  with  different  method.  If  start  position  is 
multi-byte  character’s  second  byte  or  larger,  it  starts  from  first  byte  of  multi-byte  character. 

It  subtracts  string  from  str  that  is  shorter  than  length  AND  character  that  is  not  part  of  multi-byte 
string  or  not  being  middle  of  shift  sequence. 

encoding  is  character  encoding.  If  it  is  not  set,  internal  character  encoding  is  used. 

See  also  mb_substrO,  mb_internal_encoding '). 


mb_strwidth  (php  4  >=  4.0.6) 


Return  width  of  string 


int  mb_strwidth  (string  str  [,  string  encoding]) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


mb_strwidth( )  returns  width  of  string  str. 

Multi-byte  character  usually  twice  of  width  compare  to  single  byte  character. 


Character  width 
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U+0000  -  U+0019  0 
U+0020  -  U+1FFF  1 
U+2000  -  U+FF60  2 
U+FF61  -  U+FF9F  1 
U+FFAO  -  2 


encoding  is  character  encoding.  If  it  is  omitted,  internal  encoding  is  used. 
See  also:  mb_strimwidtb'),  mb  intcrnal  encoding  ). 


mb_strimwidth  (php  4  >=  4  o  6) 


Get  truncated  string  with  specified  width 


string  mb_strimwidth  (string  str,  int  start, 
string  encoding ] ) 


int  width,  string  trimmarker  [, 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


mb_strimwidth()  truncates  string  str  to  specified  width.  It  returns  truncated  string. 

If  trimmarker  is  set,  trimmarker  is  appended  to  return  value. 

start  is  start  position  offset.  Number  of  characters  from  the  beginning  of  string.  (First  character  is  0) 
trimmarker  is  string  that  is  added  to  the  end  of  string  when  string  is  truncated. 
encoding  is  character  encoding.  If  it  is  omitted,  internal  encoding  is  used. 


Ejemplo  1.  mb_strimwidth()  example 

$str  =  mb_strimwidth ($str,  0,  40, 


See  also:  mb_strwidth '),  mb_internal_encoding[). 
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mb_convert_encoding  (php  4  >=  4.0.6) 


Convert  character  encoding 


string  mb_convert_encoding  (string  str,  string  to-encoding  [,  mixed 
from-encoding] ) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


mb_convert_encoding()  converts  character  encoding  of  string  str  from  from-encoding  to 
to-encoding. 

str  :  String  to  be  converted. 

from-encoding  is  specified  by  character  code  name  before  conversion,  it  can  be  array  or  string  - 
comma  separated  enumerated  list. 


Ejemplo  1.  mb_convert_encoding()  example 

/*  Convert  internal  character  encoding  to  SJIS  */ 

$str  =  mb_convert_encoding ($str,  "SJIS"); 

/*  Convert  EUC-JP  to  UTF-7  */ 

$str  =  mb_convert_encoding ($str,  "UTF-7",  "EUC-JP"); 

/*  Auto  detect  encoding  from  JIS,  eucjp-win,  sjis-win,  then  convert  str  to  UCS- 
2LE  */ 

$str  =  mb_convert_encoding ($str,  "UCS-2LE",  "JIS,  eucjp-win,  sjis-win"); 

/*  "auto"  is  expanded  to  "ASCII, JIS, UTF-8, EUC-JP, SJIS"  */ 

$str  =  mb_convert_encoding ($str,  "EUC-JP",  "auto"); 


See  also;  mb_detect_order'). 


mb_detect_encoding  (php  4  >=  4  0  e) 


Detect  character  encoding 
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string  mb_detect_encoding  (string  str  [,  mixed  encoding-list ]) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


mb_detect_encoding()  detects  character  encoding  in  string  str.  It  returns  detected  character  encoding. 

encoding-list  is  list  of  character  encoding.  Encoding  order  may  be  specified  by  array  or  comma 
separated  list  string. 

If  encoding_list  is  omitted,  detect_order  is  used. 


Ejemplo  1.  mb_detect_encoding()  example 

/*  Detect  character  encoding  with  current  detect_order  */ 
echo  mb_detect_encoding ( $str )  ; 

/*  "auto"  is  expanded  to  "ASCII, JIS, UTF-8, EUC-JP, SJIS"  */ 
echo  mb_detect_encoding ( $str,  "auto") ; 

/*  Specify  encoding_list  character  encoding  by  comma  separated  list  */ 
echo  mb_detect_encoding ( $str,  "JIS,  eucjp-win,  sjis-win"); 

/*  Use  array  to  specify  encoding_list  */ 

$ary [ ]  =  "ASCII"; 

$ary [ ]  =  "JIS"; 

$ary [ ]  =  "EUC-JP"; 

echo  mb_detect_encoding ( $str,  $ary)  ; 


See  also:  mb_detect_orderO- 

mb_convert_kana  (php  4  >=  4  o  6> 

Convert  "kana"  one  from  another  ("zen-kaku"  ,"han-kaku"  and  more) 

string  mb_convert_kana  (string  str,  string  option  [,  mixed  encoding ]) 
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Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


mb_convert_kana()  performs  "han-kaku"  -  "zen-kaku"  conversion  for  string  str.  It  returns  converted 
string.  This  function  is  only  useful  for  Japanese. 

option  is  conversion  option.  Default  value  is  "KV". 

encoding  is  character  encoding.  If  it  is  omitted,  internal  character  encoding  is  used. 


Applicable  Conversion  Options 


option  :  Specify  with  conversion  of  following  options.  Default  "KV" 


II  II 

Convert 

"  zen-kaku" 

alphabets  to 

"han-kaku" 

"R" 

Convert 

"han-kaku" 

alphabets  to 

"zen-kaku" 

"n" 

Convert 

" zen-kaku" 

numbers  to  "han-kaku" 

"N" 

Convert 

"han-kaku" 

numbers  to  "zen-kaku" 

"a" 

Convert 

" zen-kaku" 

alphabets  and 

numbers  to 

"han-kaku" 

"A" 

Convert 

" zen-kaku" 

alphabets  and 

numbers  to 

"han-kaku" 

(Characters  included  in  "a",  "A"  options  are 

U+0021  -  U+007E  excluding  U+0022,  U+0027,  U+005C,  U+007E) 


s  " 

Convert 

" zen-kaku 

'  space  to 

"han 

-kaku"  (U+3000  ->  U+0020) 

S" 

Convert 

"han-kaku 

'  space  to 

"  zen 

-kaku"  (U+0020  ->  U+3000) 

k" 

Convert 

" zen-kaku 

kata-kana" 

to 

"han-kaku 

kata-kana" 

K" 

Convert 

"han-kaku 

kata-kana" 

to 

" zen-kaku 

kata-kana" 

h" 

Convert 

" zen-kaku 

hira-gana" 

to 

"han-kaku 

kata-kana" 

H" 

Convert 

"han-kaku 

kata-kana" 

to 

" zen-kaku 

hira-gana" 

c" 

Convert 

" zen-kaku 

kata-kana" 

to 

"zen-kaku 

hira-gana" 

C" 

Convert 

" zen-kaku 

hira-gana" 

to 

"zen-kaku 

kata-kana" 

V" 

Collapse 

voiced  sound  notation  and  convert 

them  into  a  character 

Use  with  "Kv 


Ejemplo  1.  mb_convert_kana()  example 

/*  Convert  all  "kana"  to  "zen-kaku"  "kata-kana"  */ 

$str  =  mb_convert_kana ( $str ,  "KVC"); 

/*  Convert  "han-kaku"  "kata-kana"  to  "zen-kaku"  "kata-kana" 
and  "zen-kaku"  alpha-numeric  to  "han-kaku"  */ 

$str  =  mb_convert_kana ( $str ,  "KVa"); 
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mb_encode_mimeheader  (php  4  >=  4.0.6) 


Encode  string  for  MIME  header 


string  mb_encode_mimeheader  (string  str  [,  string  charset  [,  string 
transfer-encoding  [,  string  linefeed]]]) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


mb_encode_mimeheader()  converts  string  str  to  encoded-word  for  header  field.  It  returns  converted 
string  in  ASCII  encoding. 

charset  is  character  encoding  name.  Default  is  ISO-2022- jp. 

transfer-encoding  is  transfer  encoding.  It  should  be  one  of  "B"  (Base64)  or  "Q" 
(Quoted-Printable).  Default  is  "B". 

linefeed  is  end  of  line  marker.  Default  is  "\r\n"  (CRLF). 


Ejemplo  1.  mb_convert_kana  3  example 

$name  =  //  kanji 

$mbox  =  "kru"; 

$doma  =  "gtinn.mon"; 

$addr  =  mb_encode_mimeheader ( $name,  "UTF-7",  "Q")  .  "  <"  .  $mbox  .  "@"  .  $doma  .  ">" 

echo  $addr; 


See  also  mb_decodc_mimeheadci\). 

mb_decode_mimeheader  (php  4  >=  4 .0 ,6) 


Decode  string  in  MIME  header  field 


string  mb_decode_mimeheader  (string  str) 
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Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


mb_decode_mimeheader()  decodes  encoded-word  string  str  in  MIME  header. 
It  returns  decoded  string  in  internal  character  encoding. 

See  also  m b_c n c od c _m  i  m e h e ade r ' ) . 


mb_convert_variables  (php  4  >=  4.0.6) 


Convert  character  code  in  variable(s) 


string  mb_convert_variables  (string  to-encoding ,  mixed  from-encoding ,  mixed 
vars ) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


mb_convert_variables()  convert  character  encoding  of  variables  vars  in  encoding  from-encoding 
to  encoding  to-encoding.  It  returns  character  encoding  before  conversion  for  success,  false  for 
failure. 

mb_convert_variables()  join  strings  in  Array  or  Object  to  detect  encoding,  since  encoding  detection 
tends  to  fail  for  short  strings.  Therefore,  it  is  impossible  to  mix  encoding  in  single  array  or  object. 

It  from-encoding  is  specified  by  array  or  comma  separated  string,  it  tries  to  detect  encoding  from 

from-coding.  When  encoding  is  omitted,  detect_order  is  used. 

vars  (3rd  and  larger)  is  reference  to  variable  to  be  converted.  String,  Array  and  Object  are 
accepted.  mb_convert_variables()  assumes  all  parameters  have  the  same  encoding. 


Ejemplo  1.  mb_convert_variables()  example 

/*  Convert  variables  $postl,  $post2  to  internal  encoding  */ 

$interenc  =  mb_internal_encoding ( ) ; 

$inputenc  =  mb_convert_variables ( $interenc,  "ASCII, UTF-8, SJIS-win" ,  $postl,  $post2) 
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mb_encode_numericentity  (php  4  >=  4.0.6) 


Encode  character  to  HTML  numeric  string  reference 


string  mb_encode_numericentity  (string  str,  array  convmap  [,  string 
encoding ] ) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


mb_encode_numericentity()  converts  specified  character  codes  in  string  str  from  HTML  numeric 
character  reference  to  character  code.  It  returns  converted  string. 

array  is  array  specifies  code  area  to  convert. 

encoding  is  character  encoding. 


Ejemplo  1.  convmap  example 


$convmap  =  array  ( 

int  start_codel,  int  end_codel,  int  offsetl, 
int  start_code2,  int  end_code2,  int  offset2, 


int  maskl, 
int  mask2. 


int  start_codeN,  int  end_codeN,  int  offsetN,  int  maskN  ) ; 

//  Specify  Unicode  value  for  start_codeN  and  end_codeN 

//  Add  offsetN  to  value  and  take  bit-wise  'AND'  with  maskN,  then 

//  it  converts  value  to  numeric  string  reference. 


Ejemplo  2.  mb_encode_numericentity()  example 

/*  Convert  Left  side  of  ISO-8859-1  to  HTML  numeric  character  reference  */ 
$convmap  =  array(0x80,  Oxff,  0,  Oxff); 

$str  =  mb_encode_numericentity ($str,  $convmap,  "ISO-8859-1"); 

/*  Convert  user  defined  SJIS-win  code  in  block  95-104  to  numeric 
string  reference  */ 

$convmap  =  array ( 
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OxeOOO, 

0xe03e, 

0x1040, 

Oxffff 

0xe03f , 

OxeObb, 

0x1041, 

Oxffff 

OxeObc, 

OxeOfa, 

0x1084, 

Oxffff 

OxeOfb, 

0xel77, 

0x1085, 

Oxffff 

0xel78 , 

0xelb6, 

0xl0c8 , 

Oxffff 

0xelb7 , 

0xe233, 

0xl0c9, 

Oxffff 

0xe234, 

0xe272, 

0x110c, 

Oxffff 

0xe273, 

0xe2ef , 

OxllOd, 

Oxffff 

0xe2f 0, 

0xe32e, 

0x1150, 

Oxffff 

0xe32f , 

0xe3ab, 

0x1151, 

Oxffff 

$str  =  mb_encode_numericentity ($str,  $convmap,  "sjis-win"); 


See  also:  mb_decode_numericentity'). 


mb_decode_numericentity  (php  4  >=  4.0.6) 


Decode  HTML  numeric  string  reference  to  character 


string  mb_decode_numericentity  (string  str,  array  convmap  [,  string 
encoding ] ) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


Convert  numeric  string  reference  of  string  str  in  specified  block  to  character.  It  returns  converted  string. 
array  is  array  to  specifies  code  area  to  convert. 

encoding  is  character  encoding.  If  it  is  omitted,  internal  character  encoding  is  used. 


Ejemplo  1.  convmap  example 


$convmap  =  array  ( 
int  start_codel, 

int 

end_codel , 

int 

of fsetl, 

int 

ma  ski, 

int 

start_code2 , 

int 

end_code2 , 

int 

of f set2 , 

int 

mask2 , 

int 

start_codeN, 

int 

end_codeN, 

int 

offsetN, 

int 

maskN  ) ; 

/ /  Specify  Unicode  value  for  start_codeN  and  end_codeN 
//  Add  offsetN  to  value  and  take  bit-wise  'AND'  with  maskN, 
//  then  convert  value  to  numeric  string  reference. 
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See  also:  mb_encode_numericentity  ')- 


mb_send_mail  (php  4  >=  4.0.6) 


Send  encoded  mail. 


boolean  mb_send_mail  (string  to,  string  subject,  string  message  [,  string 
additional_headers  [,  string  additional  parameter 1 1 ) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


mb_send_mail()  sends  email.  Headers  and  message  are  converted  and  encoded  according  to 
mbjanguage'j  setting.  mb_send_mail()  is  wrapper  function  of  mail[).  See  mail 3  for  details. 

to  is  mail  addresses  send  to.  Multiple  recipients  can  be  specified  by  putting  a  comma  between  each 
address  in  to. 

subject  is  subject  of  mail. 
message  is  mail  message. 

additional_headers  is  inserted  at  the  end  of  the  header.  This  is  typically  used  to  add  extra 
headers.  Multiple  extra  headers  are  separated  with  a  newline(\n). 

additional_parameter  is  a  MTA  command  line  parameter.  It  is  useful  when  setting  the  correct 
Return-Path  header  when  using  sendmail. 

It  returns  true  for  success,  otherwise  it  returns  false. 

See  also:  mb_language\),  mail'). 


582 


XLVII.  MCAL  functions 


MCAL  stands  for  Modular  Calendar  Access  Library. 

Libmcal  is  a  C  library  for  accessing  calendars.  It’s  written  to  be  very  modular,  with  plugable  drivers. 
MCAL  is  the  calendar  equivalent  of  the  IMAP  module  for  mailboxes. 

With  meal  support,  a  calendar  stream  can  be  opened  much  like  the  mailbox  stream  with  the  IMAP 
support.  Calendars  can  be  local  file  stores,  remote  ICAP  servers,  or  other  formats  that  are  supported  by 
the  meal  library. 

Calendar  events  can  be  pulled  up,  queried,  and  stored.  There  is  also  support  for  calendar  triggers  (alarms) 
and  reoccuring  events. 

With  libmcal,  central  calendar  servers  can  be  accessed  and  used,  removing  the  need  for  any  specific 
database  or  local  hie  programming. 

To  get  these  functions  to  work,  you  have  to  compile  PHP  with  — with-mcal.  That  requires  the  meal 
library  to  be  installed.  Grab  the  latest  version  from  http://mcal.chek.com/  and  compile  and  install  it. 

The  following  constants  are  defined  when  using  the  MCAL  module:  MCAL_SUNDAY, 
MCAL_MONDAY,  MCAL_TUESDAY,  MCAL_WEDNESDAY,  MCAL_THURSDAY, 
MCAL_FRIDAY,  MCAL_SATURDAY,  MCAL_RECUR_NONE,  MCAL_RECUR_DAILY, 
MCAL_RECUR_WEEKLY,  MCAL_RECUR_MONTHLY_MDAY, 
MCAL_RECUR_MONTHLY_WDAY,  MCAL_RECUR_YEARLY,  MCAL_JANUARY, 
MCAL_FEBRUARY,  MCAL_MARCH,  MCAL_APRIL,  MCAL_MAY,  MCALJUNE,  MCALJULY, 
MC AL_AU GU GT,  MCAL_SEPTEMBER,  MCAL_OCTOBER,  MCAL_NOVEMBER,  and 
MCAL_DECEMBER.  Most  of  the  functions  use  an  internal  event  stmeture  that  is  unique  for  each 
stream.  This  alleviates  the  need  to  pass  around  large  objects  between  functions.  There  are  convenience 
functions  for  setting,  initializing,  and  retrieving  the  event  structure  values. 
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mcal_open  (PHP  3>=  3.0.13,  PHP  4  >=  4.0.0) 


Opens  up  an  MCAL  connection 


int  mcal_open  (string  calendar ,  string  username ,  string  password,  string 
options ) 


Returns  an  MCAL  stream  on  success,  false  on  error. 

mcal_open()  opens  up  an  MCAL  connection  to  the  specified  calendar  store.  If  the  optional 
options  is  specified,  passes  the  options  to  that  mailbox  also.  The  streams  internal  event  structure  is 
also  initialized  upon  connection. 


mcal_close  (PHP  3>=  3.0.13,  PHP  4  >=  4.0.0) 

Close  an  MCAL  stream 

int  mcal_close  (int  mcal_stream,  int  flags) 

Closes  the  given  meal  stream. 

mcal_fetch_event  (PHP  3>=  3.0.13,  PHP  4  >=  4.0.0) 

Fetches  an  event  from  the  calendar  stream 

object  mcal_fetch_event  (int  mcal_stream,  int  event_id  [,  int  options ]) 

mcal_fetch_event()  fetches  an  event  from  the  calendar  stream  specified  by  i  d. 

Returns  an  event  object  consisting  of: 

•  int  id  -  ID  of  that  event. 

•  int  public  -  true  if  the  event  if  public,  false  if  it  is  private. 

•  string  category  -  Category  string  of  the  event. 

•  string  title  -  Title  string  of  the  event. 

•  string  description  -  Description  string  of  the  event. 

•  int  alarm  -  number  of  minutes  before  the  event  to  send  an  alarm/reminder. 
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•  object  start  -  Object  containing  a  datetime  entry. 

•  object  end  -  Object  containing  a  datetime  entry. 

•  int  recur_type  -  recurrence  type 

•  int  recur_interval  -  recurrence  interval 

•  datetime  recur_enddate  -  recurrence  end  date 

•  int  recur_data  -  recurrence  data 

All  datetime  entries  consist  of  an  object  that  contains: 

•  int  year  -  year 

•  int  month  -  month 

•  int  mday  -  day  of  month 

•  int  hour  -  hour 

•  int  min  -  minutes 

•  int  sec  -  seconds 

•  int  alarm  -  minutes  before  event  to  send  an  alarm 


meal  list_events  (PHP  3>=  3.0.13,  PHP  4  >=  4.0.0) 


Return  a  list  of  events  between  two  given  datetimes 


array  mcal_list_events  (int  mcal_stream 
[,  int  begin_day  [,  int  end_year  [,  int 


[,  int  begin_year  [,  int  begin_month 
end_month  [,  int  end_day ] ]]]]]) 


Returns  an  array  of  event  ID’s  that  are  between  the  start  and  end  dates,  or  if  just  a  stream  is  given,  uses 
the  start  and  end  dates  in  the  global  event  structure. 

mcal_list_events()  function  takes  in  an  optional  beginning  date  and  an  end  date  for  a  calendar  stream. 
An  array  of  event  id’s  that  are  between  the  given  dates  or  the  internal  event  dates  are  returned. 


mcal_append_event  (php  4  >=  4.o.o) 

Store  a  new  event  into  an  MCAL  calendar 

int  mcal_append_event  (int  mcal_stream) 
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mcal_append_event()  Stores  the  global  event  into  an  MCAL  calendar  for  the  given  stream. 

Returns  the  uid  of  the  newly  inserted  event. 

m  ca  l_sto  re_e  ve  nt  (PHP  3>=  3.0.13,  PHP  4  >=  4.0.0) 

Modify  an  existing  event  in  an  MCAL  calendar 

int  mcal_store_event  (int  mcal_stream ) 

mcal_store_event()  Stores  the  modifications  to  the  current  global  event  for  the  given  stream. 

Returns  true  on  success  and  false  on  error. 

mcal_delete_event  (PHP  3>=  3.0.13,  PHP  4  >=  4.0.0) 

Delete  an  event  from  an  MCAL  calendar 

int  mcal_delete_event  (int  uid) 

mcal_delete_event()  deletes  the  calendar  event  specified  by  the  uid. 

Returns  true. 


mcal_snooze  (PHP  3>=  3.0.13,  PHP  4  >=  4.0.0) 

Turn  off  an  alarm  for  an  event 

int  mcal_snooze  (int  uid) 

mcal_snooze()  turns  off  an  alarm  for  a  calendar  event  specified  by  the  uid. 
Returns  true. 
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meal  list_alarms  (PHP  3>=  3.0.13,  PHP  4  >=  4.0.0) 


Return  a  list  of  events  that  has  an  alarm  triggered  at  the  given  datetime 


array  mcal_list_events  (int  mcal_stream 
[,  int  begin_day  [,  int  end_year  [,  int 


[,  int  begin_year  [,  int  begin_month 
end_month  [,  int  end_day ] ]]]]]) 


Returns  an  array  of  event  ID’s  that  has  an  alarm  going  off  between  the  start  and  end  dates,  or  if  just  a 
stream  is  given,  uses  the  start  and  end  dates  in  the  global  event  structure. 

mcal_list_events ')  function  takes  in  an  optional  beginning  date  and  an  end  date  for  a  calendar  stream.  An 
array  of  event  id’s  that  are  between  the  given  dates  or  the  internal  event  dates  are  returned. 


mcal_eventjnit  (PHP  3>=  3.0.13,  PHP  4  >=  4.0.0) 

Initializes  a  streams  global  event  structure 

int  mcal_event_init  (int  stream) 

mcal_event_init()  initializes  a  streams  global  event  structure,  this  effectively  sets  all  elements  of  the 
structure  to  0,  or  the  default  settings. 

Returns  true. 


mcal_event_set_category  (php  3>=  3.0.13,  php  4  >=  4  0  0) 

Sets  the  category  of  the  streams  global  event  structure 

int  mcal_event_set_category  (int  stream,  string  category) 

mcal_event_set_category()  sets  the  streams  global  event  structure’s  category  to  the  given  string. 
Returns  true. 


meal  event_set_title  (PHP  3>=  3.0.13,  PHP  4  >=  4.0.0) 


Sets  the  title  of  the  streams  global  event  structure 
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int  mcal_event_set_title  (int  stream,  string  title) 

mcal_event_set_title()  sets  the  streams  global  event  structure’s  title  to  the  given  string. 

Returns  true. 

mcal_event_set_description  (php  3>=  3.0.13,  php  4  >=  4.0.0 

Sets  the  description  of  the  streams  global  event  structure 

int  mcal_event_set_description  (int  stream,  string  description ) 

mcal_event_set_description()  sets  the  streams  global  event  structure’s  description  to  the  given  string. 
Returns  true. 


meal  event_set_start  (php  3>=  3013,  php  4  >=  4 .0 .0) 


Sets  the  start  date  and  time  of  the  streams  global  event  structure 


int  mcal_event_set_start  (int  stream,  int  year,  int  month,  int  [day],  int 
[hour],  int  [min],  int  [sec]) 


mcal_event_set_start()  sets  the  streams  global  event  structure’s  start  date  and  time  to  the  given  values. 
Returns  true. 


meal  event_set_end  (PHP  3>=  3.0.13,  PHP  4  >=  4.0.0) 


Sets  the  end  date  and  time  of  the  streams  global  event  structure 


int  mcal_event_set_end  (int  stream,  int  year,  int  month,  int  [day],  int 
[hour],  int  [min],  int  [sec]) 


mcal_event_set_end()  sets  the  streams  global  event  structure’s  end  date  and  time  to  the  given  values. 
Returns  true. 
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mcal_event_set_alarm  (php  3>=  3.0.13,  php  4  >=  4.0.0 

Sets  the  alarm  of  the  streams  global  event  structure 

int  mcal_event_set_alarm  (int  stream,  int  alarm) 

mcal_event_set_alarm()  sets  the  streams  global  event  structure’s  alarm  to  the  given  minutes  before  the 
event. 

Returns  true. 


mcal_event_set_class  (PHP  3>=  3.0.13,  PHP  4  >=  4.0.0) 

Sets  the  class  of  the  streams  global  event  structure 

int  mcal_event_set_class  (int  stream,  int  class) 

mcal_event_set_class()  sets  the  streams  global  event  structure’s  class  to  the  given  value.  The  class  is 
either  1  for  public,  or  0  for  private. 

Returns  true. 

mcal_isjeap_year  (PHP  3>=  3.0.13,  PHP  4  >=  4.0.0) 

Returns  if  the  given  year  is  a  leap  year  or  not 

int  mcal_is_leap_year  (int  year ) 

mcal_is_leap_year()  returns  1  if  the  given  year  is  a  leap  year,  1  if  not. 

mcal_days_in  month  (php  3>=  3.0.13,  php  4  >=  4.0.0 

Returns  the  number  of  days  in  the  given  month 

int  mcal_days_in_month  (int  month,  int  leap  year) 
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mcal_days_in_month()  Returns  the  number  of  days  in  the  given  month,  taking  into  account  if  the  given 
year  is  a  leap  year  or  not. 


mcal_date_valid  (PHP  3>=  3.0.13,  PHP  4  >=  4.0.0) 

Returns  true  if  the  given  year,  month,  day  is  a  valid  date 

int  mcal_date_valid  (int  year,  int  month,  int  day) 


mcal_date_valid()  Returns  true  if  the  given  year,  month  and  day  is  a  valid  date,  false  if  not. 


mcal_time_valid  (PHP  3>=  3.0.13,  PHP  4  >=  4.0.0) 

Returns  true  if  the  given  year,  month,  day  is  a  valid  time 

int  mcal_time_valid  (int  hour,  int  minutes ,  int  seconds ) 


mcal_time_valid()  Returns  true  if  the  given  hour,  minutes  and  seconds  is  a  valid  time,  false  if  not. 


mcaldayofweek  (PHP  3>=  3.0.13,  PHP  4  >=  4.0.0) 
Returns  the  day  of  the  week  of  the  given  date 

int  mcal_  (int  year,  int  month,  int  day) 


mcal_day_of_week()  returns  the  day  of  the  week  of  the  given  date 


mcal_day_of_year  (PHP  3>=  3.0.13,  PHP  4  >=  4.0.0) 

Returns  the  day  of  the  year  of  the  given  date 

int  mcal_  (int  year,  int  month,  int  day) 
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mcal_day_of_year()  returns  the  day  of  the  year  of  the  given  date 


mcal_date_compare  (PHP  3>=  3.0.13,  PHP  4  >=  4.0.0) 

Compares  two  dates 

int  mcal_date_compare  (int  a_year,  int  a_month,  int  a_day ,  int  b_year,  int 
b_month,  int  b_day) 


mcal_date_compare()  Compares  the  two  given  dates,  returns  <0,  0,  >0  if  a<b,  a==b,  a>b  respectively 


mcal_next_recurrence  (php  3>=  3.0.13,  php  4  >=  4.0.0 

Returns  the  next  recurrence  of  the  event 

int  mcal_next_recurrence  (int  stream,  int  weekstart ,  array  next) 


mcal_next_recurrence()  returns  an  object  filled  with  the  next  date  the  event  occurs,  on  or  after  the 
supplied  date.  Returns  empty  date  field  if  event  does  not  occur  or  something  is  invalid.  Uses  weekstart  to 
determine  what  day  is  considered  the  beginning  of  the  week. 


mcal_event_set_recur  none  (php  3>=  3015  php  4  >=  4.0.0 

Sets  the  recurrence  of  the  streams  global  event  structure 

int  mcal_event_set_recur_none  (int  stream) 


mcal_event_set_recur_none()  sets  the  streams  global  event  structure  to  not  recur  (event->recur_type  is 
set  to  MCAL_RECUR_NONE). 
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mcal_event_set_recur_daily  (php  3>=  3.0.13,  php  4  >=  4.0.0) 


Sets  the  recurrence  of  the  streams  global  event  stmcture 


int  mcal_event_set_recur_daily  (int  stream,  int  year,  int  month,  int  day, 
int  interval) 


mcal_event_set_recur_daily()  sets  the  streams  global  event  structure’s  recurrence  to  the  given  value  to 
be  reoccuring  on  a  daily  basis,  ending  at  the  given  date. 


mcal_event_set_recur_weekly  (php  3>=  3013  php  4  >=  4.0.0 


Sets  the  recurrence  of  the  streams  global  event  stmcture 


int  mcal_event_set_recur_weekly  (int  stream,  int  year,  int  month,  int  day, 
int  interval ,  int  weekdays) 


mcal_event_set_recur_weekly()  sets  the  streams  global  event  structure’s  recurrence  to  the  given  value 
to  be  reoccuring  on  a  weekly  basis,  ending  at  the  given  date. 


mcal_event_set_recur_monthly  mday  (php3>=  3.0.13,  php4>=4.o.o) 


Sets  the  recurrence  of  the  streams  global  event  stmcture 


int  mcal_event_set_recur_monthly_mday  (int  stream,  int  year,  int  month,  int 
day,  int  interval) 


mcal_event_set_recur_monthly_mday()  sets  the  streams  global  event  structure’s  recurrence  to  the 
given  value  to  be  reoccuring  on  a  monthly  by  month  day  basis,  ending  at  the  given  date. 


mcal_event_set_recur  month ly  wday  (php  3>=  3013  php  4  >=  4.o.o 


Sets  the  recurrence  of  the  streams  global  event  stmcture 
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int  mcal_event_set_recur_monthly_wday  (int  stream,  int  year,  int  month,  int 
day,  int  interval) 


mcal_event_set_recur_monthly_wday()  sets  the  streams  global  event  structure’s  recurrence  to  the 
given  value  to  be  reoccuring  on  a  monthly  by  week  basis,  ending  at  the  given  date. 


mcal_event_set_recur_yearly  (php  3>=  3.0.13,  php  4  >=  4.o.o) 


Sets  the  recurrence  of  the  streams  global  event  structure 


int  mcal_event_set_recur_yearly  (int  stream,  int  year,  int  month,  int  day, 
int  interval) 


mcal_event_set_recur_yearly()  sets  the  streams  global  event  structure’s  recurrence  to  the  given  value  to 
be  reoccuring  on  a  yearly  basis.ending  at  the  given  date  . 


mcal_fetch_current_stream_event  <php  3>=  3013  php  4  >=  4.o.0) 

Returns  an  object  containing  the  current  streams  event  structure 

int  mcal_fetch_current_stream_evGnt  (int  stream) 


mcal_event_fetch_current_stream_event()  returns  the  current  stream’s  event  structure  as  an  object 
containing: 

•  int  id  -  ID  of  that  event. 

•  int  public  -  true  if  the  event  if  public,  false  if  it  is  private. 

•  string  category  -  Category  string  of  the  event. 

•  string  title  -  Title  string  of  the  event. 

•  string  description  -  Description  string  of  the  event. 

•  int  alarm  -  number  of  minutes  before  the  event  to  send  an  alarm/reminder. 

•  object  start  -  Object  containing  a  datetime  entry. 

•  object  end  -  Object  containing  a  datetime  entry. 

•  int  recur_type  -  recurrence  type 

•  int  recur_interval  -  recurrence  interval 

•  datetime  recur_enddate  -  recurrence  end  date 
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•  int  recur_data  -  recurrence  data 

All  datetime  entries  consist  of  an  object  that  contains: 

•  int  year  -  year 

•  int  month  -  month 

•  int  mday  -  day  of  month 

•  int  hour  -  hour 

•  int  min  -  minutes 

•  int  sec  -  seconds 

•  int  alarm  -  minutes  before  event  to  send  an  alarm 


mcal_event_add_attribute  (php  3>=  3.0.15,  php  4  >=  4 .0 ,0) 

Adds  an  attribute  and  a  value  to  the  streams  global  event  structure 

void  mcal_event_add_attribute  (int  stream,  string  attribute ,  string  value) 


mcal_event_add_attribute()  adds  an  attribute  to  the  stream’s  global  event  stmcture  with  the  value  given 
by  "value"  . 
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XLVIII.  Funciones  Criptograficas 

Estas  funciones  trabajan  usando  mcrypt  (ftp://mcrypt.hellug.gr/pub/mcrypt/libmcrypt). 

Esta  es  una  interfaz  a  la  librerfa  mcrypt,  que  soporta  una  gran  variedad  de  algoritmos  de  bloque  como 
DES,  TripleDES,  Blowfish  (por  defecto),  3-WAY,  SAFER-SK64,  SAFER-SK128,  TWOFISH,  TEA, 
RC2  y  GOST  en  los  modos  de  cifrado  CBC,  OFB,  CFB  y  ECB.  Adicionalmente,  soporta  RC6  e  IDEA 
que  se  consideran  "no-libres". 

Para  usarlos,  descarga  libmcrypt-x.x.tar.gz  de  aquf  (ftp://mcrypt.hellug.gr/pub/mcrypt/libmcrypt)  y  sigue 
las  instrucciones  de  instalacion  incluidas.  Necesitas  compilar  PHP  con  el  parametro  — with-mcrypt 
para  activar  esta  extension. 

mcrypt  puede  usarse  para  encriptar  y  desencriptar  usando  los  cifrados  mencionados  arriba.  Los  cuatro 
comandos  importantes  de  mcrypt  (mcrypt_cfb(),  mcrypt_cbc '),  mcrypt_ecb '),  y  mcrypt_ofb'))  pueden 
operar  en  ambos  modos  que  se  llaman  MCRYPT_ENCRYPT  y  MCRYPT_DECRYPT,  respectivamente. 

Ejemplo  1.  Encripta  un  valor  de  entrada  con  TripleDES  en  modo  ECB 

<?php 

$key  =  "esta  es  una  clave  muy  secreta"; 

$input  =  "Nos  vemos  a  las  9  en  punto  en  el  lugar  secreto. 

$encrypted_data  =  mcrypt_ecb (MCRYPT_TripleDES,  $key,  $input,  MCRYPT_ENCRYPT) ; 
?> 

Este  ejemplo  devolvera  los  datos  encriptados  como  una  cadena  en  $encrypted_data. 

mcrypt  puede  operar  en  cuatro  modos  de  cifrado  (CBC,  OFB,  CFB  y  ECB).  Perfilaremos  el  uso  normal 
de  cada  uno  de  estos  modos.  Para  una  mejor  referencia  y  una  discusion  mas  completa  ver  Applied 
Cryptography  by  Schneier  (ISBN  0-471-11709-9). 

•  ECB  (electronic  codebook  o  libro  de  codigos  electronico)  va  bien  para  datos  aleatorios,  tales  como 
encriptar  otras  claves.  Puesto  que  los  datos  son  cortos  y  aleatorios,  las  desventajas  de  ECB  tienen  un 
efecto  negativo  favorable. 

•  CBC  (cipher  block  chaining  o  cifrado  en  bloque  encadenado)  es  especialmente  util  para  encriptar 
ficheros,  donde  incrementa  significativamente  la  seguridad  por  encima  de  ECB. 

•  CFB  (cipher  feedback  o  cifrado  realimentado)  es  el  mejor  modo  de  encriptar  flujos  de  bytes  donde 
cada  byte  debe  ser  encriptado. 

•  OFB  (output  feedback  o  salida  realimentada)  es  comparable  al  CFB,  pero  puede  usarse  en 
aplicaciones  donde  la  propagacion  de  errores  no  puede  tolerarse. 


Actualmente  PHP  no  soporta  el  encriptado/desencriptado  de  flujos  de  bits.  Por  ahora,  solo  soporta  el 
manejo  de  cadenas. 

Para  una  lista  completa  de  los  cifrados  soportados,  ver  las  definiciones  al  final  de  mcrypt. h.  La  regia 
general  es  que  se  puede  acceder  al  cifrado  desde  PHP  con  MCRYPT_nombredelcifrado. 

Aquf  hay  una  pequena  lista  de  los  cifrados  que  estan  soportados  actualmente  por  la  extension  mcrypt.  Si 
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un  cifrado  no  esta  listado  aquf,  pero  esta  listado  por  mcrypt  como  soportado,  puedes  asumir  con 
seguridad  que  esta  documentacion  esta  caduca. 


mcrypt 


•  MCRYPT_BLOWFISH 

•  MCRYPT_DES 

•  MCRYPT_TripleDES 

•  MCRYPT_ThreeWAY 

•  MCRYPT_GOST 

•  MCRYPT_CRYPT 

•  MCRYPT_DES_COMPAT 

•  MCRYPT_SAFER64 

•  MCRYPT_SAFER128 

•  MCRYPT_CAST128 

•  MCRYPT_TEAN 

•  MCRYPT_RC2 

•  MCRYPT_TWOFISH  (para  las  antiguas  versiones  mcrypt  2.x) 

•  MCRYPT_TWOFISH128  (TWOFISHxxx  esta  disponible  en  las  versiones  mas  nuevas  2.x) 

•  MCRYPT_TWOFISH  1 92 

•  MCRYPT_TWOFISH256 

•  MCRYPT_RC6 

•  MCRYPT  JDEA 


Debes  (en  los  modos  CFB  y  OFB)  o  puedes  (en  el  modo  CBC)  suministrar  un  vector  de  inicializacion 
(IV)  a  la  correspondiente  funcion  de  cifrado.  El  IV  debe  ser  unico  y  debe  ser  el  mismo  cuando 
desencriptas  o  encriptas.  Con  datos  que  son  guardados  encriptados,  puedes  cojer  la  salida  de  una  funcion 
de  Indice  bajo  la  cual  los  datos  son  almacenados  (ej.  la  clave  MD5  de  un  fichero).  Alternativamente, 
puedes  transmitir  el  IV  junto  con  los  datos  encriptados  (ver  capftulo  9.3  de  Applied  Cryptography  by 
Schneier  (ISBN  0-471-11709-9)  para  una  discusion  de  este  asunto). 
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mcrypt 


Obtiene  el  nombre  del  cifrado  especificado 


string  mcrypt_get_cipher_name  (int  cipher) 


mcrypt_get_cipher_name()  se  usa  para  obtener  el  nombre  del  cifrado  especificado. 

mcrypt_get_cipher_name()  toma  como  argumento  el  numero  de  cifrado  y  devuelve  el  nombre  del 
cifrado  o  false,  si  el  cifrado  no  existe. 


Ejemplo  1.  Ejemplo  de  mcrypt_get_cipher_name 

<?php 

$cipher  =  MCRYPT_TripleDES ; 

print  mcrypt_get_cipher_name ( $cipher )  ; 
?> 


El  ejemplo  de  mas  arriba  da  como  resultado: 
TripleDES 


mcrypt_get_block_size  php  3>=  3 .0 ,8,  php  4  >=  4.o.o 

Obtiene  el  tamano  de  bloque  del  cifrado  indicado 

int  mcrypt_get_block_size  (int  cipher ) 

mcrypt_get_block_size()  se  usa  para  obtener  el  tamano  de  bloque  del  cifrado  indicado  en  cipher. 
mcrypt_get_block_size()  toma  un  argumento,  el  cifrado  cipher  y  devuelve  el  tamano  en  bytes. 
Ver  tambien:  mcrypt_get_key_size ') 
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mcrypt_get_key_size  <php  3>=  3.o.8,  php  4  >=  4.0.0 

Obtiene  el  tamano  de  la  clave  de  un  cifrado 


int  mcrypt_get_key_size  (int  cipher) 


mcrypt_get_key_size()  se  usa  para  obtener  el  tamano  de  la  clave  del  cifrado  indicado  en  cipher. 

mcrypt_get_key_size()  toma  un  argumento,  el  cifrado  cipher  y  devuelve  el  tamano  de  la  clave  en 
bytes. 

Ver  tambien:  mcrypt_get_block_size ') 


mcrypt_create_iv  (PHP  3>=  3.0.8,  PHP  4  >=  4.0.0) 

Crea  un  vector  de  inicializacion  (IV)  a  partir  de  una  fuente  aleatoria 

string  mcrypt_create_iv  (int  size,  int  source) 


mcrypt_create_iv()  se  usa  para  crear  un  IV. 

mcrypt_create_iv()  toma  dos  argumentos,  size  determina  el  tamano  del  IV,  source  especifica  la 
fuente  del  IV. 

La  fuente  puede  ser  MCRYPT_RAND  (generador  de  numeros  aleatorios  del  sistema), 
MCRYPT_DEV_RANDOM  (que  lee  datos  de  /dev/random)  y  MCRYPT_DEV_URANDOM  (que  lee 
datos  de  /dev/urandom).  Si  usas  MCRYPT_RAND,  asegurate  de  llamar  antes  a  srand()  para  inicializar  el 
generador  de  numeros  aleatorios. 


Ejemplo  1.  Ejemplo  de  mcrypt_create_iv 

<?php 

$cipher  =  MCRYPT_TripleDES ; 

$block_size  =  mcrypt_get_block_size ($cipher)  ; 

$iv  =  mcrypt_create_iv ($block_size,  MCRYPT_DEV_RANDOM) ; 
?> 
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mcrypt 


Encripta/desencripta  datos  en  modo  CBC 

int  mcrypt_cbc  (int  cipher,  string  key,  string  data,  int  mode  [,  string  iv] ) 

mcrypt_cbc()  encripta  o  desencripta  (dependiendo  de  mode )  los  datos  data  con  el  cifrado  cipher  y 
la  clave  key  en  el  modo  de  cifrado  CBC  y  devuelve  la  cadena  resultante. 

El  parametro  cipher  es  una  de  las  constantes  con  nombre  MCRYPT_nombrecifrado. 

key  es  la  clave  suministrada  al  algoritmo.  Debe  guardarse  en  secreto. 

data  son  los  datos  que  seran  encriptados/desencriptados. 

mode  es  MCRYPT_ENCRYPT  o  MCRYPT_DECRYPT. 

i  v  es  el  vector  de  inicializacion  opcional. 

Ver  tambien:  mcrypt_cfb {),  mcrypt_ecbO,  mcrypt_ofbO 

mcrypt_cfb  (PHP  3>=  3.0.8,  PHP  4  >=  4.0.0) 

Encripta/desencripta  datos  en  modo  CFB 

int  mcrypt_cfb  (int  cipher,  string  key,  string  data,  int  mode,  string  iv) 

mcrypt_cfb()  encripta  o  desencripta  (dependiendo  de  mode )  los  datos  data  con  el  cifrado  cipher  y 
la  clave  key  en  el  modo  de  cifrado  CFB  y  devuelve  la  cadena  resultante. 

El  parametro  cipher  es  una  de  las  constantes  con  nombre  MCRYPT_nombrecifrado. 

key  es  la  clave  suministrada  al  algoritmo.  Debe  guardarse  en  secreto. 

data  son  los  datos  que  seran  encriptados/desencriptados. 

mode  es  MCRYPT_ENCRYPT  o  MCRYPT_DECRYPT. 

i  v  es  el  vector  de  inicializacion. 

Ver  tambien:  mcrypt_cbc(),  mcrypt_ecb(),  mcrypt_ofb() 

mcrypt_ecb  (PHP  3>=  3.0.8,  PHP  4  >=  4.0.0) 

Encripta/desencripta  datos  en  modo  ECB 
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int  mcrypt_ecb  (int  cipher,  string  key,  string  data,  int  mode) 


mcrypt_ecb()  encripta  o  desencripta  (dependiendo  de  mode )  los  datos  data  con  el  cifrado  cipher  y 
la  clave  key  en  el  modo  de  cifrado  ECB  y  devuelve  la  cadena  resultante. 

El  parametro  cipher  es  una  de  las  constantes  con  nombre  MCRYPT_nombrecifrado. 

key  es  la  clave  suministrada  al  algoritmo.  Debe  guardarse  en  secreto. 

data  son  los  datos  que  seran  encriptados/desencriptados. 

mode  es  MCRYPT_ENCRYPT  o  MCRYPT_DECRYPT. 

Ver  tambien:  mcrypt_cbc'),  mcrypt_cfb  '),  mcrypt_otb  ') 


mcrypt_ofb  (PHP  3>=  3.0.8,  PHP  4  >=  4.0.0) 

Encripta/desencripta  datos  en  modo  OFB 

int  mcrypt_ofb  (int  cipher,  string  key,  string  data,  int  mode,  string  iv) 

mcrypt_ofb()  encripta  o  desencripta  (dependiendo  de  mode )  los  datos  data  con  el  cifrado  cipher  y 
la  clave  key  en  el  modo  de  cifrado  OFB  y  devuelve  la  cadena  resultante. 

El  parametro  cipher  es  una  de  las  constantes  con  nombre  MCRYPT_nombrecifrado. 

key  es  la  clave  suministrada  al  algoritmo.  Debe  guardarse  en  secreto. 

data  son  los  datos  que  seran  encriptados/desencriptados. 

mode  es  MCRYPT_ENCRYPT  o  MCRYPT_DECRYPT. 

i  v  es  el  vector  de  inicializacion. 

Ver  tambien:  mcrypt_cbc(),  mcrypt_cfb0,  mcrypt_ecb() 
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XLIX.  Funciones  Hash 


Estas  funciones  han  sido  realizadas  para  trabajar  con  mhash  (http://mhash.sourceforge.net/). 

Esta  es  una  interfaz  con  al  libreria  mhash.  mhash  soporta  una  amplia  variedad  de  algoritmos  hash  como 
MD5,  SHA1,  GOST,  y  muchos  otros. 

Para  usarla,  hay  que  descargar  la  distribucion  desde  su  sitio  web  (http://mhash.sourceforge.net/)  y  seguir 
las  intrucciones  de  instalacion.  Se  necesita  compilar  PHP  con  el  parametr  — with-mhash  para  activar 
esta  extension. 

mhash  puede  ser  usado  para  crear  checksums,  message  digests,  y  mas. 


Ejemplo  1.  Generar  una  clave  SHA1  e  imprimirla  en  hexadecimal 

<?php 

$input  =  "Let  us  meet  at  9  o'  clock  at  the  secret  place."; 

$hash  =  mhash (MHASH_SHA1 ,  $input); 

print  "The  hash  is  " . bin2hex ( $hash) . "\n"; 

?> 

Esto  generara: 

The  hash  is  d3b85d710d8f 6e4e5efd4d5e67d041f 9cecedafe 

PAra  una  lista  complera  de  hash  soportados,  refierase  a  la  documentation  de  mhash.  La  regia  general  es 
que  se  puede  acceder  a  los  algoritmos  hash  desde  PHP  con  MHASH_HASHNAME.  Como  ejemplo,  para 
acceder  a  HAVAL  se  debe  usar  la  constante  de  PHP  llamada  MHASH_HAVAL. 

Aqui  hay  una  lista  de  hashes  que  esta  actualmente  soportada  por  mhash.  Si  un  hash  no  esta  en  dicha  lista 
pero  aparece  como  soportado  por  mhash,  entonces  se  asume  con  plena  seguridad  que  esta 
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documentation  esta  desfasada. 

•  MHASH_MD5 

•  MHASH_SHA1 

•  MHASH_HAVAL 

•  MHASH_RIPEMD  1 60 

•  MHASH_RIPEMD128 

•  MHASH_SNEFRU 

•  MHASH_TIGER 

•  MHASH_GOST 

•  MHASH_CRC32 

•  MHASH_CRC32B 
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mhash_get_hash  name  (php  3>=  3.0.9,  php  4  >=  4.o.o) 

Conseguir  el  nombre  de  un  hash  especifico 

string  mhash_get_hash_name  (int  hash) 

mhash_get_hash_name()  es  usado  para  conseguir  el  nombre  de  el  hash  determinado. 

mhash_get_hash_name()  toma  el  id  del  hash  como  un  argumento  y  devuelve  el  nombre  de  el  hash  o 
false,  si  el  hash  no  existe. 

Ejemplo  1.  mhash_get_hash_name  example 

<?php 

$hash  =  MHASH_MD5; 

print  mhash_get_hash_name ($hash)  ; 

?> 

El  ejemplo  anterior  mostrara: 

MD5 


mhash_get_block_size  (php  3>=  3  0  9  php  4  >=  4 .0 .0) 

Conseguir  el  tamano  de  bloque  de  el  hash  especificado 

int  mhash_get_block_size  (int  hash) 


mhash_get_block_size()  es  usado  para  obtener  el  tamano  de  un  bloque  de  el  hash  determinado. 

mhash_get_block_size()  toma  un  argumento,  el  hash  y  devuelve  el  tamano  en  bytes  o  false,  si  el 
hash  no  existe. 


mhashcount  (PHP  3>=  3.0.9,  PHP  4  >=  4.0.0) 


Obtener  el  valor  mayor  del  id  hash  disponible 
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int  mhash_count  (void) 


mhash_count()  devuelve  el  valor  mas  alto  id  hash  disponible.  Los  hash  estan  numerados  desde  0  hasta 
este  valor. 


Ejemplo  1.  Recorriendo  todos  los  hash 

<?php 

$nr  =  mhash_count ( )  ; 

for($i  =  0;  $i  <=  $nr;  $i++)  { 

echo  sprintf("The  blocksize  of  %s  is  %d\n", 
mhash_get_hash_name ($i)  , 
mhash_get_block_size ($i) ) ; 

} 

?> 


mhash  (PHP  3>=  3.0.9,  PHP  4  >=  4.0.0) 


Calcular  el  hash 


string  mhash  (int  hash,  string  data ) 


mhash()  aplica  una  funcion  hash  especificada  por  hash  a  data  y  devuelve  el  valor  hash  resultante 
(tambien  llamdo  digest). 
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mssql_close  (PHP  3,  PHP  4  >=  4.0.0) 


MS  SQL  Server 


cierra  una  conexion  con  MS  SQL  Server 

int  mssql_close  (int  link_identifier) 


Devuleve:  true  si  se  finaliza  con  exito,  false  si  se  produce  un  error 

mssql_close()  cierra  la  conexion  con  una  base  de  datos  MS  SQL  Server  que  esta  asociada  al  identificador 
especificado.  Si  el  identificador  no  se  especifica,  se  asume  la  ultima  conexion  abierta. 

Observe  que  normalmente  esto  no  es  necesario,  ya  que  las  conexiones  no-persistentes  abiertas  se  cierran 
automaticamente  en  cuanto  finaliza  el  script. 

mssql_close()  no  cerrara  conexiones  persistentes  generadas  por  mssql_pconnect(). 

Ver  tambien:  mssql_connectO,  mssql_pcoiincct '). 


mssql_connect  (PHP  3,  PHP  4  >=  4.0.0) 

abre  una  conexion  con  MS  SQL  server 

int  mssql_connect  (string  servername ,  string  username ,  string  password) 


Devuelve:  Un  identificador  de  MSSQL  si  se  ejecuta  correctamente,  o  false  si  se  produce  un  error. 

mssql_connect()  establece  una  conexion  con  MS  SQL  server.  El  argumento  servername  debe  ser  un 
nombre  de  servidor  valido,  que  esta  definido  en  el  fichero  ’interfaces’. 

En  caso  de  hacer  una  segunda  llamada  a  mssql_connect()  con  los  mismos  argumentos,  no  se  establecera 
una  nueva  conexion,  sino  que  se  devolvera  el  identificador  de  la  conexion  establecida  anteriormente. 

La  conexion  con  el  servidor  se  cerrara  tan  pronto  como  finalice  el  script,  a  menos  que  se  cierre  antes, 
mediante  una  llamada  explicita  a  la  funcion  mssql  close  ). 

Ver  tambien  mssql  pconnect  ),  mssql_close(). 


mssql_data_seek  (PHP  3,  PHP  4  >=  4.0.0) 

mueve  el  puntero  interno  de  las  filas 

int  mssql_data_seek  (int  result_identifier,  int  row_number) 


606 


MS  SQL  Server 


Devuelve:  true  si  se  ejecuta  con  exito,  false  si  falla. 

mssql_data_seek()  mueve  el  puntero  interno  de  la  consulta  MS  SQL  asociada  al  result_identifier 
especificado,  para  que  apunte  al  numero  de  fila  especificada.  La  siguiente  llamada  a  mssql_fetch_row ') 
devolvera  esa  fila. 

Ver  tambien:  mssql_data_seek(). 


mssql_fetch_array  (php  3,  php 4 >=  4.0.0 


Captura  la  fila  en  un  array 


int  mssql_fetch_array  (int  result ) 


Devuelve:  Un  array  que  corresponde  a  la  fila  capturada,  o  false  si  no  hay  mas  filas. 

mssql_fetch_array()  es  una  version  extendida  de  mssql_fetch_row  ').  Anade  el  almacenar  los  datos  en  los 
indices  numericos  del  array  resultante,  tambien  almacena  los  datos  en  indices  asociativos,  usando  los 
nombres  de  los  campos  como  claves. 

Una  observacion  a  tener  en  cuenta  es,  que  usar  mssql_fetch_array()  NO  es  mas  lento  que  usar 
mssql_fetch_row(),  mientras  que  esta  provee  un  valor  attadido  significativo. 

Para  mas  detalles,  ver  tambien  mssql_fetch_row ') 


mssql_fetch_f ield  (php  3,  php  4  >=  4.0.0) 

obtiene  la  informacion  de  los  campos 

object  mssql_fetch_field  (int  result,  int  field_offset) 


Devuleve  un  objeto  que  contiene  informacion  de  los  campos. 

mssql_fetch_field()  se  puede  usar  para  obtener  informacion  acerca  de  los  campos  pertenecientes  al 
resultado  de  una  consulta.  Si  el  parametro  field_offset  no  es  especificado,  se  devuelve  la  informacion  del 
siguiente  campo  que  todavfa  no  ha  sido  devuelto  por  mssql_fetch_field(). 

Las  propiedades  de  este  objeto  son: 

•  name  -  nombre  de  la  columna.  si  la  columna  es  el  resultado  de  una  funcion,  esta  propiedad  vale  #N, 
donde  #N  es  un  numero  de  serie. 

•  column_source  -  la  tabla  de  donde  se  tomo  la  columna 

•  max_length  -  longitud  maxima  de  columna 
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•  numeric  -  1  si  la  columna  es  numerica 
Ver  tambien  mssq[_fickl_seel< ') 


mssql_fetch_object  (php  3,  php  4  >=  4.0.0 


captura  la  fila  como  un  objeto 


int  mssql_fetch_ob ject  (int  result) 


Devuelve:  Un  objeto  con  propiedades  que  se  corresponden  con  la  fila  capturada,  o  false  si  no  hay  mas 
filas. 

mssql_fetch_object()  es  parecida  a  mssq l_fetch_array '),  con  una  diferencia  -  devuelve  un  objeto  en  vez 
de  un  array.  Indirectamente,  esto  significa  que  solo  se  puede  acceder  a  los  datos  por  el  nombre  de  los 
campos,  y  no  por  sus  posiciones  en  el  objeto  (los  numeros  no  son  nombres  de  propiedades  validas). 

La  funcion  es  identica  a  mssql_fetch_array  '),  y  casi  tan  rapida  como  mssql_fetch_row ')  (la  diferencia  es 
insignificante). 

Ver  tambien:  mssq l_fetch-array ')  and  mssql_fetch-row  ). 


mssql_fetch_row  (php  3,  php  4  >=  4.0.0 


obtiene  la  fila  como  un  array  numerado 


array  mssql_fetch_row  (int  result ) 


Devuleve:  Un  array  que  corresponde  a  la  fila  capturada,  o  false  si  no  hay  mas  filas. 

mssql_fetch_row()  captura  una  fila  de  datos  pertenecientes  al  resultado  asociado  con  el  identificador  de 
resultado  especihcado.  La  fila  es  devuelta  como  un  array.  Cada  columna  de  resultados  es  almacenada  en 
una  posicion  del  array,  comenzando  en  la  posicion  0. 

Siguientes  llamadas  a  mssql_fetch_rows()  devolverfan  las  filas  siguientes  del  result  set,  o  false  si  no 
hay  mas  filas. 

Ver  tambien:  mssql_fetch_arrayO,  mssql_fetch_objectO,  mssql_data_seek/),  mssql_fetch_lengths(),  and 
mssqlresult). 
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mssql_f ield_seek  (php  3,  php  4  >=  4.0.0 

set  field  offset 

int  mssql_f ield_seek  (int  result,  int  field_offset) 

Se  posiciona  en  el  campo  especificado  por  el  parametro  field_offset.  Si  la  siguiente  llamada  a 
mssql_fetch_field ')  no  incluye  el  parametro  field_offset,  lo  que  devuelve  la  funcion  es  el  campo. 

Ver  tambien:  mssql_fetch_field'). 

mssql_f  ree_result  (php  3,  php  4  >=  4.0.0) 

libera  de  la  memoria  el  resultado  de  una  consulta 

int  mssql_f ree_result  (int  result ) 

mssql_free_result()  solo  se  necesita  llamarla  si  le  preocupa  el  estar  usando  mucha  memoria  mientras  se 
esta  ejecutando  el  script.  Toda  el  resultado  en  memoria  sera  liberado  automaticamente  cuando  finalice  el 
script,  puede  llamar  a  mssql_free_result()  con  el  identificador  de  la  consulta  como  argumento  y  la 
consulta  asociada  sera  liberada  de  la  memoria. 

mssql_num_f ields  <php 3  php 4 >=  4.0.0 

obtiene  el  numero  de  campos  de  la  consulta 

int  mssql_num_f ields  (int  result) 

mssql_num_fields()  devuelve  el  numero  de  campos  de  la  consulta  o  result  set. 

Ver  tambien:  mssql_db_query(),  mssql_query '),  mssql_fetch_field\),  mssql_num_rowsp. 

mssql_num_rows  <php 3  php 4 >=  4.0.0 

obtiene  el  numero  de  bias  de  la  consulta 
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int  mssql_num_rows  (string  result) 

mssql_num_rows()  devuelve  el  numero  de  filas  de  la  consulta  o  result  set. 
Ver  tambien:  mssql_db_query(),  mssql_query ')  and,  mssql_fetch_row\). 


mssql_pconnect  (php 3,  php 4 >=  4.0.0 

abre  una  conexion  persistenete  con  MS  SQL 

int  mssql  pconnect  (string  servername ,  string  username ,  string  password) 


Devuelve:  Un  identificador  persistente  postivo  si  no  hay  error,  o  false  si  se  produce  alguno 

mssql_pconnect()  funciona  de  la  misma  forma  que  mssql_connectO  aunque  con  dos  grandes  diferencias. 

La  primera  es  que  cuando  intenta  conectar,  la  funcion  intentara  encontrar  un  enlace  (persistente)  que  ya 
este  abierto  en  el  mismo  ordenador,  nombre  de  usuario  y  contrasena.  Si  lo  encuentra,  la  funcion 
devolvera  el  identificador  de  esta  en  vez  de  abrir  una  nueva  conexion. 

Y  la  segunda,  la  conexion  con  el  servidor  no  se  cerrara  cuando  finalice  la  ejecucion  del  script.  En  vez  de 
esto,  el  enlace  permanecera  abierto  para  un  uso  futuro.  (mssql_close  )  no  cerrara  enlaces  establecidos 

por  mssql_pconnect ( )  ). 

Por  consiguiente,  este  tipo  de  enlace  es  llamado  ’persistente’. 


mssql_query  (php  3,  php  4  >=  4.0.0 

envia  una  consulta  MS  SQL 

int  mssql_query  (string  query,  int  link_identifier) 


Devuelve:  Un  identificado  de  resultado  valido  si  no  hay  error,  o  false  en  caso  contrario. 

mssql_query()  envia  una  petition  de  consulta  a  la  base  de  datos  activa  en  el  servidor  asociada  al 
identificador  de  enlace  especificado.  Si  el  identificador  del  enlace  no  es  especificado,  se  asume  como 
abierto  el  ultimo  enlace.  Si  no  hay  ningun  enlace  abierto,  la  funcion  intenta  establecer  un  enlace  como  si 
mssql_connect')  hubiera  sido  llamada,  y  lo  usa. 

Ver  tambien:  mssql_db_query(),  mssql_select_db'),  and  mssql_conncct'). 
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get  result  data 


int  mssql_result  (int  result,  int  i,  mixed  field) 


Devuelve:  El  contenido  de  la  celda  en  la  fila  y  posicion  del  result  set  especificado. 

mssql_result()  devuelve  el  contenido  de  una  celda  del  result  set.  El  parametro  field  puede  ser  la  posicion 
del  campo,  o  el  nombre  del  campo  o  bien  nombretabla.nombrecampo.  Si  el  nombre  de  la  columna  ha 
sido  renombrado  (’select  foo  as  bar  from...’),  use  el  alias  en  vez  del  nombre  de  la  columna. 

Trabajando  con  result  sets  de  gran  tarn  ado,  deberfa  considerar  el  uso  de  una  de  las  funciones  que 
capturan  una  fila  completa  (especificadas  abajo).  Como  estas  funciones  devuelven  el  contenido  de 
multiples  celdas  en  una  sola  llamada,  estas  son  MUCHO  mas  rapidas  que  mssql_result().  Tambien, 
observe  que  especificar  una  posicion  numerica  para  el  argumento  field  es  mucho  mas  rapido  que 
especificar  el  nombre  de  un  campo  o  utilizar  la  forma  nombretabla.nombrecampo  como  argumento. 

Alternativas  recomendadas  para  mayor  rendimiento  :  mssql_fetch_row  '),  mssql_fetch_array '),  y 

mssql_fetch_object'). 


mssql_select_db  <php 3,  php 4 >=  4 .0 ,0) 

selecciona  una  base  de  datos  MS  SQL 

int  mssql_select_db  (string  database_name ,  int  link_identifier) 


Devuelve:  true  si  todo  va  bien,  false  si  se  produce  un  error 

mssql_select_db()  selecciona  como  base  de  datos  activa  del  servidor,  la  que  esta  asociada  al  identificador 
de  enlace  especificado.  Si  no  se  especifica  nigun  identificador,  se  asume  el  ultimo  enlace.  Si  no  hay 
ningun  enlace  abierto,  la  funcion  intentara  establecer  un  enlace  como  si  se  llamara  a  la  funcion 
mssql_con  ncct'),  y  lo  usa. 

Cada  llamada  a  mssql_queryO  sera  realizada  sobre  la  base  de  datos  activa. 

Ver  tambien:  mssql  conncct  ),  mssql_pconncct '),  y  mssql_query ') 
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Aviso 

This  module  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  these 
functions,  these  function  names,  in  concreto  ANYTHING  documented  here  can 
change  in  a  future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this 
module  at  your  own  risk. 


Introduction 


Ming  is  an  open-source  (LGPL)  library  which  allows  you  to  create  SWF  ("Flash")  format  movies.  Ming 
supports  almost  all  of  Flash  4’s  features,  including:  shapes,  gradients,  bitmaps  (pngs  and  jpegs),  morphs 
("shape  tweens"),  text,  buttons,  actions,  sprites  ("movie  clips"),  streaming  mp3,  and  color 
transforms— the  only  thing  that’s  missing  is  sound  events. 

Ming  is  not  an  acronym. 

Note  that  all  values  specifying  length,  distance,  size,  etc.  are  in  "twips",  twenty  units  per  pixel.  That’s 
pretty  much  arbitrary,  though,  since  the  player  scales  the  movie  to  whatever  pixel  size  is  specified  in  the 
embed/object  tag,  or  the  entire  frame  if  not  embedded. 

Ming  offers  a  number  of  advantages  over  the  existing  PHP/libswf  module.  You  can  use  Ming  anywhere 
you  can  compile  the  code,  whereas  libswf  is  closed-source  and  only  available  for  a  few  platforms, 
Windows  not  one  of  them.  Ming  provides  some  insulation  from  the  mundane  details  of  the  SWF  file 
format,  wrapping  the  movie  elements  in  PHP  objects.  Also,  Ming  is  still  being  maintained;  if  there’s  a 
feature  that  you  want  to  see,  just  let  us  know  ming@opaque.net  (mailto:ming@opaque.net). 

Ming  was  added  in  PHP  4.0.5. 


Installation 


To  use  Ming  with  PHP,  you  first  need  to  build  and  install  the  Ming  library.  Source  code  and  installation 
instructions  are  available  at  the  Ming  home  page  :  http://www.opaque.net/ming/  along  with  examples,  a 
small  tutorial,  and  the  latest  news. 

Download  the  ming  archive.  Unpack  the  archive.  Go  in  the  Ming  directory,  make,  make  install. 

This  will  build  libming.  so  and  install  it  into  /usr/lib/,  and  copy  ming.h  into  /usr/include/. 
Edit  the  prefix=  line  in  the  Makefile  to  change  the  installation  directory. 


built  into  php  (unix) 

mkdir  <phpdir>/ext/ming 
cp  php_ext/*  <phpdir>/ext/ming 
cd  <phpdir> 
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./buildconf 

./configure  — with-ming  <other  config  options> 


Ming  (flash) 


Build  and  install  php  as  usual.  Restart  web  server  if  necessary 

built  into  php  (unix) 

download  php_ming .  so .  gz.  uncompress  it  and  copy  it  to  your  php  modules  directory,  (you  can  find 
your  php  module  directory  by  running  php-config  — extension-dir).  Now  either  just  add 
extension=php_ming .  so  to  your  php  .  ini  file,  or  put  dl  ( '  php_ming .  so'  )  ;  at  the  head  of  all  of 
your  Ming  scripts. 


How  to  use  Ming 

Ming  introduces  13  new  object  in  PHP,  all  with  matching  methods  and  attributes.  To  use  them,  you  need 
to  know  about  objects 

•  swfmovie'). 

•  swfshape'). 

•  swfdisplayitemj). 

•  swfgradient). 

•  swfbitmap '). 

•  swffillO. 

•  swfmorph'). 

•  swftext'). 

•  swffontj). 

•  swftextfieldj). 

•  swfsprite '). 

•  swfbutton'). 

•  swfaction'). 
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SWFMovie  (PHP  4  >=  4.0.5) 


Ming  (flash) 


Creates  a  new  movie  object,  representing  an  SWF  version  4  movie. 


new  swfmovie  ( ) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


swfmovieO  creates  a  new  movie  object,  representing  an  SWF  version  4  movie. 

SWFMovie  has  the  following  methods  :  swfmovie->output(),swfmovie->save(),  swfmovie->add(), 
swfmovie->remove(),  swfmovie->nextframe(),  swfmovie->setbackground(),  swfmovie->setrate(), 
swfmovie->setdimension(),  swfmovie->setframes()  and  swfmovie->streammp3(). 

See  examples  in  :  swfdisplayitem->rotateto(),  swfshape->setline(),  swfshape->addfill()...  Any 

example  will  use  this  object. 


SWFMovie->output  (unknown) 


Dumps  your  lovingly  prepared  movie  out. 


void  swfmovie->output  () 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


swfmovie->output()  dumps  your  lovingly  prepared  movie  out.  In  PHP,  preceding  this  with  the  command 

<?php 

header ( ' Content -type :  appl i cat i on /x- shockwave- flash' ) ; 

?> 


convinces  the  browser  to  display  this  as  a  flash  movie. 
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Ming  (flash) 


See  also  swfmovie->save(). 

See  examples  in  :  swfmovie->streammp3(),  swfdisplayitem->rotateto(),  swfaction ')...  Any  example 
will  use  this  method. 


SWFMovie->save  (unknown) 


Saves  your  movie  in  a  hie. 


void  swfmovie->save  (string  filename) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


swfmovie->save()  saves  your  movie  to  the  hie  named  filename. 
See  also  outputQ. 


SWFMovie->add  (unknown) 

Adds  any  type  of  data  to  a  movie. 

void  swfmovie->add  (ressource  instance) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


swfmovie->add()  adds  instance  to  the  current  movie,  instance  is  any  type  of  data  :  Shapes,  text, 
fonts,  etc.  must  all  be  add’ed  to  the  movie  to  make  this  work. 

For  displayable  types  (shape,  text,  button,  sprite),  this  returns  an  SWFDispIayItem(),  a  handle  to  the 
object  in  a  display  list.  Thus,  you  can  add  the  same  shape  to  a  movie  multiple  times  and  get  separate 
handles  back  for  each  separate  instance. 
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See  also  all  other  objects  (adding  this  later),  and  swfmovie->remove() 
See  examples  in  :  swfdisplayitem->rotateto()  and  swfshape->addfill(). 


Ming  (flash) 


SWFMovie->remove  (unknown) 

Removes  the  object  instance  from  the  display  list. 

void  swfmovie->remove  (resource  instance) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


swfmovie->remove()  removes  the  object  instance  instance  from  the  display  list. 
See  also  swfmovie->add(). 


SWFMovie->setbackground  (unknown) 


Sets  the  background  color. 


void  swfmovie->setbackground  (int  red,  int  green,  int  blue) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


swfmovie->setbackground()  sets  the  background  color.  Why  is  there  no  rgba  version?  Think  about  it. 
(Actually,  that’s  not  such  a  dumb  question  after  all-  you  might  want  to  let  the  html  background  show 
through.  There’s  a  way  to  do  that,  but  it  only  works  on  IE4.  Search  the  http://www.macromedia.com/  site 
for  details.) 
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SWFMovie->setrate  (unknown) 


Ming  (flash) 


Sets  the  animation’s  frame  rate. 


void  swfmovie->setrate  (int  rate) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


swfmovie->setrate()  sets  the  frame  rate  to  rate,  in  frame  per  seconds.  Animation  will  slow  down  if  the 
player  can’t  render  frames  fast  enough-  unless  there’s  a  streaming  sound,  in  which  case  display  frames 
are  sacrificed  to  keep  sound  from  skipping. 


SWFMovie->setdimension  (unknown) 


Sets  the  movie’s  width  and  height. 


void  swfmovie->setdimension  (int  width,  int  height) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


swfmovie->setdimension()  sets  the  movie’s  width  to  width  and  height  to  height. 


SWFMovie->setframes  (unknown) 

Sets  the  total  number  of  frames  in  the  animation. 


void  swfmovie->setf rames  (string  numberof frames) 
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Ming  (flash) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


swfmovie->setframes()  sets  the  total  number  of  frames  in  the  animation  to  numberof  frames. 


SWFMovie->nextframe  (unknown) 


Moves  to  the  next  frame  of  the  animation. 


void  swfmovie->next frame  () 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


swfmovie->setframes()  moves  to  the  next  frame  of  the  animation. 


SWFMovie->streammp3  (unknown) 


Streams  a  MP3  file. 


void  swfmovie->streammp3  (string  mp3FileName) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


swfmovie->streammp3()  streams  the  mp3  file  mp3FileName.  Not  very  robust  in  dealing  with  oddities 
(can  skip  over  an  initial  ID3  tag,  but  that’s  about  it).  Like  SWFShape->addJpegFill(),  this  isn’t  a  stable 
function-  we’ll  probably  need  to  make  a  separate  SWFSound  object  to  contain  sound  types. 
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Ming  (flash) 


Note  that  the  movie  isn’t  smart  enough  to  put  enough  frames  in  to  contain  the  entire  mp3  stream-  you’ll 
have  to  add  (length  of  song  *  frames  per  second)  frames  to  get  the  entire  stream  in. 

Yes,  now  you  can  use  ming  to  put  that  rock  and  roll  devil  worship  music  into  your  SWF  files.  Just  don’t 
tell  the  RIAA. 

Ejemplo  1.  swfmovie->streammp3()  example 


<?php 

$m  =  new  SWFMovie ( ) ; 

$m->setRate (12.0) ; 

$m->streamMp3 ( "distortobass . mp3 " ) ; 

/ /  use  your  own  MP3 

//  11.85  seconds  at  12.0  fps  =  142  frames 
$m->setFrames (142) ; 

header ( ' Content-type :  application/x-shockwave-f lash' ) ; 
$m->output  ( ) ; 


SWFDisplayltem  (unknown) 


Creates  a  new  displayitem  object. 


new  swfdisplayitem  () 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


swfdisplayitemO  creates  a  new  swfdisplayitem  object. 

Here’s  where  all  the  animation  takes  place.  After  you  define  a  shape,  a  text  object,  a  sprite,  or  a  button, 
you  add  it  to  the  movie,  then  use  the  returned  handle  to  move,  rotate,  scale,  or  skew  the  thing. 

SWFDisplayltem  has  the  following  methods  :  swfdisplayitem->move(),  swfdisplayitem->moveto(), 
swfdisplayitem->scaleto(),  swfdisplayitem->scale(),  swfdisplayitem->rotate(), 
swfdisplayitem->rotateto(),  swfdisplayitem->skewxto(),  swfdisplayitem->skewx(), 
swfdisplayitem->skewyto()  swfdisplayitem->skewyto(),  swfdisplayitem->setdepth() 
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swfdisplayitem->remove(),  swfdisplayitem->setname()  swfdisplayitem->setratio(), 
swfdisplayitem->addcolor()  and  swfdisplayitem->multcolor(). 


Ming  (flash) 


SWFDisplayltem->moveTo  (unknown) 

Moves  object  in  global  coordinates. 


void  swfdisplayitem->moveto  (int  x,  int  y) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


swfdisplayitem->moveto()  moves  the  current  object  to  (x,y)  in  global  coordinates. 

The  object  may  be  a  swfshape'),  a  swfbutton '),  a  swftext))  or  a  swf sprite')  object.  It  must  have  been 
added  using  the  swfmovie->add(). 

See  also  swfdisplayitem->move(). 


SWFDisplayltem->move  (unknown) 


Moves  object  in  relative  coordinates. 


void  swfdisplayitem->move  (int  dx,  int  dy) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


swfdisplayitem->move()  moves  the  current  object  by  (dx,dy)  from  its  current  position. 

The  object  may  be  a  swfshapej),  a  swfbutton 0,  a  swftextj)  or  a  swfspritej)  object.  It  must  have  been 
added  using  the  swfmovie->add(). 

See  also  swfdispIayitem->moveto(). 
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SWFDisplayltem->scaleTo  (unknown) 


Ming  (flash) 


Scales  the  object  in  global  coordinates. 


void  swfdisplayitem->scaleto  (int  x,  int  y) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


swfdisplayitem->scaleto()  scales  the  current  object  to  (x,y)  in  global  coordinates. 

The  object  may  be  a  swfshapej),  a  swfbuttonO,  a  swftext')  or  a  swfspritej)  object.  It  must  have  been 
added  using  the  swfmovie->add(). 

See  also  swfdisplayitem->scale(). 


SWFDisplayltem->scale  (unknown) 

Scales  the  object  in  relative  coordinates. 


void  swfdisplayitem->scale  (int  dx,  int  dy) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


swfdisplayitem->scale()  scales  the  current  object  by  (dx,dy)  from  its  current  size. 

The  object  may  be  a  swfshape'),  a  swfbuttonO,  a  swftext  )  or  a  swf sprite')  object.  It  must  have  been 
added  using  the  swfmovie->add(). 

See  also  swfdisplayitem->scaleto(). 
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SWFDisplayltem->rotateTo  (unknown) 


Ming  (flash) 


Rotates  the  object  in  global  coordinates. 


void  swfdisplayitem->rotateto  (float  degrees) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


swfdisplayitem->rotateto()  set  the  current  object  rotation  to  degrees  degrees  in  global  coordinates. 

The  object  may  be  a  swfshapej),  a  swfbuttonO,  a  swftextj)  or  a  swfspritej)  object.  It  must  have  been 
added  using  the  swfmovie->add(). 

This  example  bring  three  rotating  string  from  the  background  to  the  foreground.  Pretty  nice. 

Ejemplo  1.  swfdisplayitem->rotateto()  example 

<?php 

$thetext  =  "ming!"; 

$f  =  new  SWFFont ( "Bauhaus  93.fdb"); 

$m  =  new  SWFMovie ( ) ; 

$m-> set Rate (24.0) ; 

$m->setDimension (2400,  1600); 

$m->setBackground ( Oxf f ,  Oxff,  Oxff ) ; 

/ /  functions  with  huge  numbers  of  arbitrary 
//  arguments  are  always  a  good  idea!  Really! 

function  text($r,  $g,  $b,  $a,  $rot,  $x,  $y,  $scale,  $string) 

{ 

global  $f,  $m; 

$t  =  new  SWFText  () ; 

$t->setFont ($f) ; 

$t->setColor ($r,  $g,  $b,  $a) ; 

$t->setHeight (960) ; 

$t->moveTo (- ( $f->get Width ($string) ) /2,  $f->getAscent ( )  /  2  )  ; 

$t->addString ( $string) ; 

//  we  can  add  properties  just  like  a  normal  php  var, 

//  as  long  as  the  names  aren't  already  used. 

//  e.g.,  we  can't  set  $i->scale,  because  that's  a  function 
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Ming  (flash) 


$i  =  $m->add($t); 

$i->x  =  $x; 

$i->y  =  $y ; 

$i->rot  =  $rot; 

$i->s  =  $scale; 

$i->rotateTo ($rot) ; 

$i->scale ( $scale,  $scale) ; 

//  but  the  changes  are  local  to  the  function,  so  we  have  to 
//  return  the  changed  object.  kinda  weird.. 

return  $i; 

} 


function  step($i) 

{ 

$oldrot  =  $i->rot; 

$i->rot  =  1 9*$i->rot /20 ; 

$i->x  =  ( 1 9*$i->x  +  1200) /20; 

$i->y  =  ( 1 9*$i->y  +  800) /20; 
$i->s  =  ( 1 9*$i->s  +  1.0) /20; 

$i->rotateTo ($i->rot) ; 
$i->scaleTo  ($i->s,  $i->s) ; 
$i->moveTo ( $i->x,  $i->y) ; 

return  $i; 

} 


//  see?  it  sure  paid  off  in  legibility: 


$il 

=  text (Oxff, 

0x33, 

0x33 , 

Oxff, 

900, 

1200, 

800, 

0.03,  $thetext ) ; 

$i2 

=  text  (0x00, 

0x33, 

Oxff, 

0x7f , 

-560, 

.  1200, 

,  800, 

0.04,  $thetext ) ; 

$i3 

=  text (Oxff, 

Oxff, 

Oxff, 

0x9f, 

180, 

1200, 

800, 

0.001,  $thetext) ; 

for($i=l;  $i<=100;  ++$i) 

{ 

$il  =  step  ( $ i 1 ) ; 

$i2  =  step  ( $ i 2 )  ; 

$i3  =  step  ( $ i 3 ) ; 

$m->nextFrame () ; 

} 

header ( ' Content -type :  application/ x-shockwave-f lash' ) ; 
$m->output ( ) ; 


See  also  swfdisplayitem->rotate(). 
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SWFDisplayltem->Rotate  (unknown) 


Ming  (flash) 


Rotates  in  relative  coordinates. 


void  swfdisplayitem->rotate  (float  ddegrees) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


swfdisplayitem->rotate()  rotates  the  current  object  by  ddegrees  degrees  from  its  current  rotation. 

The  object  may  be  a  swfshapej),  a  swfbutton)),  a  swftextj)  or  a  swfspritej)  object.  It  must  have  been 
added  using  the  swfmovie->add(). 

See  also  swfdisplayitem->rotateto(). 


SWFDisplayltem->skewXTo  (unknown) 

Sets  the  X-skew. 


void  swfdisplayitem->skewxto  (float  degrees) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


swfdisplayitem->skewxto()  sets  the  x-skew  to  degrees.  For  degrees  is  1.0,  it  means  a  45-degree 
forward  slant.  More  is  more  forward,  less  is  more  backward. 

The  object  may  be  a  swfshapc'),  a  swfbutton '),  a  swftext  )  or  a  swfspritej)  object.  It  must  have  been 
added  using  the  swfmovie->add(). 

See  also  swfdisplayitem->skewx(),  swfdisplayitem->skewy()  and  swfdisplayitem->skewyto(). 
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SWFDisplayltem->skewX  (unknown) 


Ming  (flash) 


Sets  the  X-skew. 


void  swfdisplayitem->skewx  (float  ddegrees) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


swfdisplayitem->skewx()  adds  ddegrees  to  current  x-skew. 

The  object  may  be  a  swfshapej),  a  swfbuttonO,  a  swftextj)  or  a  swfspritej)  object.  It  must  have  been 
added  using  the  swfmovie->add(). 

See  also  swfdisplayitem->skewx(),  swfdisplayitem->skewy()  and  swfdisplayitem->skewyto(). 


SWFDisplayltem->skewYTo  (unknown) 

Sets  the  Y-skew. 


void  swfdisplayitem->skewyto  (float  degrees) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


swfdispIayitem->skewyto()  sets  the  y-skew  to  degrees.  For  degrees  is  1.0,  it  means  a  45-degree 
forward  slant.  More  is  more  upward,  less  is  more  downward. 

The  object  may  be  a  swfshape'),  a  swfbutton '),  a  swftext  )  or  a  swfsprite')  object.  It  must  have  been 
added  using  the  swfmovie->add(). 

See  also  swfdisplayitem->skewy(),  swfdisplayitem->skewx()  and  swfdisplayitem->skewxto(). 
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SWFDisplayltem->skewY  (unknown) 


Ming  (flash) 


Sets  the  Y-skew. 


void  swfdisplayitem->skewy  (float  ddegrees) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


swfdisplayitem->skewy()  adds  ddegrees  to  current  y-skew. 

The  object  may  be  a  swfshapej),  a  swfbuttonO,  a  swftextj)  or  a  swfspritej)  object.  It  must  have  been 
added  using  the  swfmovie->add(). 

See  also  swfdisplayitem->skewyto(),  swfdisplayitem->skewx()  and  swfdisplayitem->skewxto(). 


SWFDisplayltem->setDepth  (unknown) 


Sets  z-order 


void  swfdisplayitem->setdepth  (float  depth) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


swfdispIayitem->rotate()  sets  the  object’s  z-order  to  depth.  Depth  defaults  to  the  order  in  which 
instances  are  created  (by  add’ing  a  shape/text  to  a  movie)-  newer  ones  are  on  top  of  older  ones.  If  two 
objects  are  given  the  same  depth,  only  the  later-defined  one  can  be  moved. 

The  object  may  be  a  swfshapej),  a  swfbutton'),  a  swftextj)  or  a  swfspritej)  object.  It  must  have  been 
added  using  the  swfmovie->add(). 
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Removes  the  object  from  the  movie 


void  swfdisplayitem->remove  () 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


swfdisplayitem->remove()  removes  this  object  from  the  movie’s  display  list. 

The  object  may  be  a  swfshapej),  a  swfbuttonO,  a  swftextj)  or  a  swfspritej)  object.  It  must  have  been 
added  using  the  swfmovie->add(). 

See  also  swfmovie->add(). 


SWFDisplayltem->setName  (unknown) 

Sets  the  object’s  name 


void  swfdisplayitem->setname  (string  name) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


swfdisplayitem->setname()  sets  the  object’s  name  to  name,  for  targetting  with  action  script.  Only 
useful  on  sprites. 

The  object  may  be  a  swfshape'),  a  swfbuttonO,  a  swftext)  or  a  swfsprite')  object.  It  must  have  been 
added  using  the  swfmovie->add(). 
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SWFDisplayltem->setRatio  (unknown) 


Ming  (flash) 


Sets  the  object’s  ratio. 


void  swfdisplayitem->setratio  (float  ratio) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


swfdisplayitem->setratio()  sets  the  object’s  ratio  to  ratio.  Obviously  only  useful  for  morphs. 

The  object  may  be  a  swfshapej),  a  swfbutton)),  a  swftextj)  or  a  swfspritej)  object.  It  must  have  been 
added  using  the  swfmovie->add(). 

This  simple  example  will  morph  nicely  three  concentric  circles. 

Ejemplo  1.  swfdisplayitem->setname()  example 

<?php 

$p  =  new  SWFMorph ( ) ; 


$g  =  new  SWFGradient ( )  ; 


$g->addEntry (0.0, 

0,  0, 

0)  ; 

$g->addEntry (0.16, 

Oxff, 

Oxff, 

Oxff 

$g->addEntry (0.32, 

0,  0, 

0)  ; 

$g->addEntry (0.48, 

Oxff, 

Oxff, 

Oxff 

$g->addEntry (0.64, 

0,  0, 

0)  ; 

$g->addEntry (0.80, 

Oxff, 

Oxff, 

Oxff 

$g->addEntry (1.00, 

0,  0, 

0)  ; 

$s  =  $p->getShapel ( )  ; 

$f  =  $s->addFill ($g,  SWFFILL_RADIAL_GRADIENT)  ; 
$f->scaleTo(0.05)  ; 

$s->setLeftFill ( $ f )  ; 

$s->movePenTo  (-160,  -120); 

$s->drawLine  (320,  0) ; 

$s->drawLine  (0,  240); 

$s->drawLine (-320,  0); 

$s->drawLine (0,  -240); 

$g  =  new  SWFGradient ( ) ; 

$g->addEntry ( 0 . 0 ,  0,  0,  0); 

$g->addEntry ( 0 . 1 6 ,  Oxff,  0,  0); 

$g->addEntry ( 0 . 32 ,  0,  0,  0); 

$g->addEntry  (0 . 48,  0,  Oxff,  0); 
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$g->addEntry  ( 0 . 64 ,  0,  0,  0); 

$g->addEntry  (0 . 80,  0,  0,  Oxff) ; 

$g->addEntry (1 . 00,  0,  0,  0); 

$s  =  $p->getShape2  ( ) ; 

$f  =  $s->addFill ($g,  SWFFILL_RADIAL_GRADIENT) ; 
$f->scaleTo(0.05) ; 

$f->skewXTo (1.0) ; 

$s->setLeftFill ( $  f ) ; 

$s->movePenTo  (-160,  —12  0) ; 

$s->drawLine  (320,  0) ; 

$s->drawLine  (0,  240); 

$s->drawLine  (-320,  0); 

$s->drawLine  (0,  -240); 

$m  =  new  SWFMovie ( ) ; 

$m->setDimension (320,  240); 

$i  =  $m->add ( $p) ; 

$i->moveTo  (160,  120); 

for($n=0;  $n<=1.001;  $n+=0.01) 

{ 

$i->setRatio ( $n) ; 

$m->nextFrame () ; 

} 

header ( ' Content-type :  application/x-shockwave-f lash' ) ; 
$m->output ( ) ; 


SWFDisplayltem->addColor  (unknown) 

Adds  the  given  color  to  this  item’s  color  transform. 


void  swfdisplayitem->addcolor  ( [int  red  [,  int  green  [,  int  blue  [,  int 
a] ]  ]  ]  ) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 
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swfdisplayitem->addcolor()  adds  the  color  to  this  item’s  color  transform.  The  color  is  given  in  its  RGB 
form. 

The  object  may  be  a  swfshapc'),  a  swfbutton '),  a  swftext')  or  a  swfsprite')  object.  It  must  have  been 
added  using  the  swfmovie->add(). 


SWFDisplayltem->multColor  (unknown) 


Multiplies  the  item’s  color  transform. 


void  swfdisplayitem->multcolor  (  [int  red  [,  int  green  [,  int  blue  [,  int 
a] ]  ]  ]  ) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


swfdisplayitem->multcolor()  multiplies  the  item’s  color  transform  by  the  given  values. 

The  object  may  be  a  swfshapej),  a  swfbutton (),  a  swftext')  or  a  swfspritej)  object.  It  must  have  been 
added  using  the  swfmovie->add(). 

This  simple  example  will  modify  your  picture’s  atmospher  to  Halloween  (use  a  landscape  or  bright 
picture). 

Ejemplo  1.  swfdisplayitem->multcolor()  example 


<?php 

$b  =  new  SWFBitmap ( "backyard . jpg" ) ; 

//  note  use  your  own  picture  :-) 

$s  =  new  SWF Shape  0  ; 

$s->setRightFill ($s->addFill ($b) ) ; 

$s->drawLine ( $b->getwidth ( ) ,  0) ; 

$s->drawLine  (0,  $b->getHeight () ) ; 

$s->drawLine (-$b->getwidth ( ) ,  0 ) ; 

$s->drawLine  (0,  -$b->getHeight () ) ; 

$m  =  new  SWFMovie ( ) ; 

$m->setDimension ( $b->getwidth () ,  $b->getHeight () ) ; 

$i  =  $m->add ( $  s ) ; 

for($n=0;  $n<=20;  ++$n) 
f 
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$i->multColor ( 1 . 0-$n/10 ,  1.0,  1.0); 
$i->addColor ( Oxf f *$n/20 ,  0,  0); 
$m->nextFrame () ; 


header ( ' Content-type :  application/x-shockwave-f lash' ) ; 
$m->output ( ) ; 


SWFShape  (PHP  4  >=  4.0.5) 


Creates  a  new  shape  object. 


new  swf shape  () 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


swfshapeO  creates  a  new  shape  object. 

SWFShape  has  the  following  methods  :  swfshape->setline(),  swfshape->addfill(), 
swfshape->setleftfill(),  swfshape->setrightfill(),  swfshape->movepento(),  swfshape->movepen(), 
swfshape->drawlineto(),  swfshape->drawline(),  swfshape->drawcurveto()  and 
swfshape->drawcurve() . 

This  simple  example  will  draw  a  big  red  elliptic  quadrant. 

Ejemplo  1.  swfshapeO  example 


<?php 

$s  =  new  SWFShape (); 

$s->setLine  ( 40,  0x7f,  0,  0); 
$s->setRightFill ( $s->addFill ( Oxf f ,  0,  0) ) ; 
$s->movePenTo  (200,  200); 

$s->drawLineTo ( 62 00,  200); 

$s->drawLineTo ( 62 00,  4600); 

$s->drawCurveTo (200,  4600,  200,  200); 

$m  =  new  SWFMovie ( ) ; 

$m->setDimension ( 6400,  4800); 
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$m->setRate (12.0)  ; 

$m->add ($s) ; 

$m->nextFrame () ; 

header ( ' Content-type :  application/x-shockwave-f lash' ) ; 
$m->output ( ) ; 


SWFShape->setLine  (unknown) 


Sets  the  shape’s  line  style. 


void  swf shape->setline  (int  width  [,  int  red  [,  int  green  [,  int  blue  [,  int 
a] ]  ]  ]  ) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


swfshape->setline()  sets  the  shape’s  line  style,  width  is  the  line’s  width.  If  width  is  0,  the  line’s  style 
is  removed  (then,  all  other  arguments  are  ignored).  If  width  >  0,  then  line’s  color  is  set  to  red,  green, 
blue.  Last  parameter  a  is  optional. 

swfshape->setline()  accepts  1,  4  or  5  arguments  (not  3  or  2). 

You  must  declare  all  line  styles  before  you  use  them  (see  example). 

This  simple  example  will  draw  a  big  "!#%*@",  in  funny  colors  and  gracious  style. 

Ejemplo  1.  swfshape->setline()  example 


<?php 

$s  =  new  SWFShapeO; 

$fl  =  $s->addFill (Oxff ,  0,  0); 

$f 2  =  $s->addFill (Oxff ,  0x7f,  0); 

$f 3  =  $s->addFill (Oxff,  Oxff,  0); 

$f 4  =  $s->addFill (0,  Oxff,  0); 

$f 5  =  $s->addFill (0,  0,  Oxff) ; 

//  bug:  have  to  declare  all  line  styles  before  you  use  them 
$s->setLine  ( 40,  0x7f,  0,  0); 

$s->setLine  ( 40,  0x7f,  0x3f,  0) ; 
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$s->setLine  ( 40,  0x7f,  0x7f,  0) ; 

$s->setLine ( 40 ,  0,  0x7f,  0); 

$s->setLine  ( 40 ,  0,  0,  0x7 f) ; 

$f  =  new  SWFFont (' Techno . fdb' ) ; 

$s->setRightFill ($fl) ; 

$s->setLine  ( 40 ,  0x7f,  0,  0); 

$s->drawGlyph  ($f ,  '  !  ' ) ; 

$s->movePen ( $f->getwidth ('!'),  0 ) ; 

$s->setRightFill ($f2) ; 

$s->setLine ( 40 ,  0x7f,  0x3f,  0) ; 

$s->drawGlyph  ($f , 

$s->movePen ( $f->getwidth ('#'),  0 ) ; 

$s->setRightFill ($f3) ; 

$s->setLine  ( 40 ,  0x7f,  0x7f,  0) ; 

$s->drawGlyph ($f ,  '%'); 

$s->movePen ( $f->getwidth ('%'),  0 ) ; 

$s->setRightFill ( $  f  4 ) ; 

$s->setLine  ( 40 ,  0,  0x7f,  0); 

$s->drawGlyph  ($f , 

$s->movePen ( $f->getwidth ('*'),  0 ) ; 

$s->setRightFill ( $  F5 ) ; 

$s->setLine ( 40 ,  0,  0,  0x7 f) ; 

$s->drawGlyph  ($f ,  ' 

$m  =  new  SWFMovie  ( ) ; 

$m-> set Dimens ion (3000,2000) ; 

$m->setRate (12.0) ; 

$i  =  $m->add($s); 

$i->moveTo ( 1500-$f->getWidth ( " ! #%*@ " ) /2 ,  1000  +  $f->getAscent  0/2); 

header ( ' Content-type :  application/x-shockwave-f lash' ) ; 

$m->output  ( ) ; 


SWFShape->addFill  (unknown) 


Adds  a  solid  fill  to  the  shape. 


void  swf shape->addf ill  (int  red,  int  green,  int  blue  [,  int  a]) 
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Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


void  swf shape->addf ill  (SWFbitmap  bitmap  [,  int  flags] ) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


void  swf shape->addf ill  (SWFGradient  gradient  [,  int  flags]) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


swfshape->addfill()  adds  a  solid  fill  to  the  shape’s  list  of  fill  styles.  swfshape->addfill()  accepts  three 
different  types  of  arguments. 

red,  green,  bl  ue  is  a  color  (RGB  mode).  Last  parameter  a  is  optional. 

The  bitmap  argument  is  an  swfbitmap')  object.  The  flags  argument  can  be  one  of  the  following 
values  :  SWFFILL_CLIPPED_BITMAP  or  SWFFILL_TILED_BITMAP.  Default  is 
SWFFILL_TILED_BITMAP.  I  think. 

The  gradient  argument  is  an  swfgradientj  object.  The  flags  argument  can  be  one  of  the  following 
values  :  SWFFILL_RADIAL_GRADIENT  or  SWFFILL_LINEAR_GRADIENT.  Default  is 
SWFFILL_LINEAR_GRADIENT.  I’m  sure  about  this  one.  Really. 

swfshape->addfill()  returns  an  swffi  1 1 ')  object  for  use  with  the  swfshape->setleftfill()  and 
swfshape->setrightfill()  functions  described  below. 

See  also  swfshape->setleftfill()  and  swfshape->setrightfill(). 
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This  simple  example  will  draw  a  frame  on  a  bitmap.  Ah,  here’s  another  buglet  in  the  flash  player-  it 
doesn’t  seem  to  care  about  the  second  shape’s  bitmap’s  transformation  in  a  morph.  According  to  spec, 
the  bitmap  should  stretch  along  with  the  shape  in  this  example.. 

Ejemplo  1.  swfshape->addfill()  example 

<?php 

$p  =  new  SWFMorph ( ) ; 

$b  =  new  SWFBitmap ( " alphaf ill . jpg" )  ; 

/ /  use  your  own  bitmap 
$width  =  $b->getwidth ( ) ; 

$height  =  $b->getHeight ( ) ; 

$s  =  $p->getShapel  ( ) ; 

$f  =  $S->addFill ($b,  SWFFILL_TILED_BITMAP ) ; 

$f->moveTo (-$width/2 ,  -$height / 4 ) ; 

$f->scaleTo  ( 1 . 0 ,  0.5); 

$s->setLeftFill  ($f ) ; 

$s->movePenTo (-$width/ 2 ,  -$height / 4 ) ; 

$s->drawLine ($width,  0); 

$s->drawLine  (0,  $height/2) ; 

$s->drawLine (-$width,  0); 

$s->drawLine (0,  -$height/2); 

$s  =  $p->getShape2  ( ) ; 

$f  =  $S->addFill ($b,  SWFFILL_TILED_BITMAP ) ; 

//  these  two  have  no  effect! 

$f->moveTo (-$width/4,  -$height/2) ; 

$f->scaleTo  ( 0 . 5 ,  1.0); 

$s->setLeftFill  ($f ) ; 

$s->movePenTo (-$width/ 4 ,  -$height / 2 ) ; 

$s->drawLine ( $width/2 ,  0); 

$s->drawLine  (0,  $height); 

$s->drawLine (-$width/2 ,  0); 

$s->drawLine  (0,  -$height) ; 

$m  =  new  SWFMovie ( ) ; 

$m->setDimension ( $width,  $height) ; 

$i  =  $m->add($p); 

$i->moveTo ($width/2,  $height/2) ; 

for($n=0;  $n<1.001;  $n+=0.03) 

{ 

$i->setRatio  ($n) ; 

$m->nextFrame () ; 

} 

header ( ' Content-type :  application/x-shockwave-f lash' ) ; 

$m->output ( ) ; 
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?> 


SWFShape->setLeftFill  (unknown) 

Sets  left  rasterizing  color. 


void  swf shape->setleftf ill  (swf gradient  fill) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


void  swfshape->setleftfill  (int  red,  int  green,  int  blue  [,  int  a]) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


What  this  nonsense  is  about  is,  every  edge  segment  borders  at  most  two  fills.  When  rasterizing  the  object, 
it’s  pretty  handy  to  know  what  those  fills  are  ahead  of  time,  so  the  swf  format  requires  these  to  be 
specified. 

swfshape->setleftfill()  sets  the  fill  on  the  left  side  of  the  edge-  that  is,  on  the  interior  if  you’re  defining 
the  outline  of  the  shape  in  a  counter-clockwise  fashion.  The  fill  object  is  an  SWFFill  object  returned 
from  one  of  the  addFill  functions  above. 

This  seems  to  be  reversed  when  you’re  defining  a  shape  in  a  morph,  though.  If  your  browser  crashes,  just 
try  setting  the  fill  on  the  other  side. 

Shortcut  for swf shape->set left fill ( $s->addf ill ( $r,  $g,  $b  [,  $a]));. 

See  also  swfshape->setrightfill(). 
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Sets  right  rasterizing  color. 


void  swf shape->setrightfill  (swfgradient  fill) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


void  swf shape->setrightfill  (int  red,  int  green,  int  blue  [,  int  a]) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


See  also  swfshape->setleftfill(). 

Shortcut  for  swfshape->setrightfill  ($s->addfill  ($r,  $g,  $b  [,  $  a  ]  )  )  ; . 


SWFShape->movePenTo  (unknown) 


Moves  the  shape’s  pen. 


void  swf shape->movepento  (int  x,  int  y) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 
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swfshape->setrightfill()  move  the  shape’s  pen  to  (x,y)  in  the  shape’s  coordinate  space. 

See  also  swfshape->movepen(),  swfshape->drawcurveto(),  swfshape->drawlineto()  and 
swfshape->drawline() . 


SWFShape->movePen  (unknown) 


Moves  the  shape’s  pen  (relative). 


void  swf shape->movepen  (int  dx,  int  dy) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


swfshape->setrightlill()  move  the  shape’s  pen  from  coordinates  (current  x,current  y)  to  (current  x  +  dx, 
current  y  +  dy)  in  the  shape’s  coordinate  space. 

See  also  swfshape->movepento(),  swfshape->drawcurveto(),  swfshape->drawlineto()  and 
swfshape->drawline() . 


SWFShape->drawLineTo  (unknown) 


Draws  a  line. 


void  swf shape->drawlineto  (int  x,  int  y) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


swfshape->setrightlill()  draws  a  line  (using  the  current  line  style,  set  by  swfshape->setline())  from  the 
current  pen  position  to  point  (x,y)  in  the  shape’s  coordinate  space. 

See  also  swfshape->movepento(),  swfshape->drawcurveto(),  swfshape->movepen()  and 
swfshape->drawline() . 
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SWFShape->drawLine  (unknown) 


Ming  (flash) 


Draws  a  line  (relative). 


void  swf shape->drawline  (int  dx,  int  dy) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


swfshape->setrightfill()  draws  a  line  (using  the  current  line  style  set  by  swfshape->setline())  from  the 
current  pen  position  to  displacement  ( dx,dy ). 

See  also  swfshape->movepento(),  swfshape->drawcurveto(),  swfshape->movepen()  and 
swfshape->drawlineto() . 


SWFShape->drawCurveTo  (unknown) 


Draws  a  curve. 


void  swf shape->drawcurveto  (int  controlx ,  int  controly ,  int  anchorx ,  int 
anchory ) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


swfshape->drawcurveto()  draws  a  quadratic  curve  (using  the  current  line  style,  set  by 
swfshape->setline())  from  the  current  pen  position  to  (anchorx, anchory)  using 
(controlx, controly)  as  a  control  point.  That  is,  head  towards  the  control  point,  then  smoothly  turn 
to  the  anchor  point. 

See  also  swfshape->drawlineto(),  swfshape->drawline(),  swfshape->movepento()  and 
swfshape->movepen(). 
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SWFShape->drawCurve  (unknown) 


Ming  (flash) 


Draws  a  curve  (relative). 


void  swf shape->drawcurve  (int  controldx ,  int  controldy ,  int  anchordx ,  int 
anchordy) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


swfshape->drawcurve()  draws  a  quadratic  curve  (using  the  current  line  style, set  by 
swfshape->setline())  from  the  current  pen  position  to  the  relative  position  ( anchorx,anchory )  using 
relative  control  point  ( controlx,controly ).  That  is,  head  towards  the  control  point,  then  smoothly 
turn  to  the  anchor  point. 

See  also  swfshape->drawlineto(),  swfshape->drawline(),  swfshape->movepento()  and 
swfshape->movepen(). 


SWFGradient  (PHP  4  >=4.0.5) 


Creates  a  gradient  object 


new  swf gradient  ( ) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


swfgradient()  creates  a  new  SWFGradient  object. 

After  you’ve  added  the  entries  to  your  gradient,  you  can  use  the  gradient  in  a  shape  fill  with  the 
swfshape->addfill()  method. 

SWFGradient  has  the  following  methods  :  swfgradient->addentry(). 

This  simple  example  will  draw  a  big  black-to-white  gradient  as  background,  and  a  redish  disc  in  its 
center. 
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Ming  (flash) 


Ejemplo  1.  swfgradient()  example 

<?php 

$m  =  new  SWFMovie ( ) ; 

$m->setDimension (320,  240); 

$s  =  new  SWFShapeO; 

/ /  first  gradient-  black  to  white 
$g  =  new  SWFGradientO; 

$g->addEntry ( 0 . 0 ,  0,  0,  0)  ; 

$g->addEntry ( 1 . 0 ,  Oxff,  Oxff,  Oxff); 

$f  =  $s->addFill ($g,  SWFFILL_LINEAR_GRADIENT) ; 
$f->scaleTo(0.01) ; 

$f->moveTo (160,  120); 

$s->setRightFill ( $  f ) ; 

$s->drawLine (320,  0) ; 

$s->drawLine  (0,  240); 

$s->drawLine (-320,  0); 

$s->drawLine  (0,  -240); 

$m->add ($s) ; 

$s  =  new  SWFShapeO; 

/ /  second  gradient-  radial  gradient  from  red  to  transparent 
$g  =  new  SWFGradientO; 

$g->addEntry ( 0 . 0 ,  Oxff,  0,  0,  Oxff); 

$g->addEntry ( 1 . 0 ,  Oxff,  0,  0,  0); 

$f  =  $s->addFill ($g,  SWFFILL_RADIAL_GRADIENT) ; 
$f->scaleTo(0.005) ; 

$f->moveTo (160,  120); 

$s->setRightFill ( $  f ) ; 

$s->drawLine  (320,  0) ; 

$s->drawLine (0,  240); 

$s->drawLine (-320,  0); 

$s->drawLine  (0,  -240); 

$m->add ($s) ; 

header ( ' Content -type :  application/ x-shockwave-f lash' ) ; 
$m->output ( ) ; 
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SWFG  rad  ient->add  Entry  (unknown) 


Ming  (flash) 


Adds  an  entry  to  the  gradient  list. 


void  swfgradient->addentry  (float  ratio,  int  red,  int  green,  int  blue  [,  int 
a]  ) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


swfgradient»addentry()  adds  an  entry  to  the  gradient  list,  ratio  is  a  number  between  0  and  1 
indicating  where  in  the  gradient  this  color  appears.  Thou  shalt  add  entries  in  order  of  increasing  ratio. 

red,  green,  blue  is  a  color  (RGB  mode).  Last  parameter  a  is  optional. 


SWFBitmap  (PHP  4  >=4.0.5) 

Loads  Bitmap  object 

new  swfbitmap  (string  filename  [,  int  alpha filename] ) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


swfbitmapO  creates  a  new  SWFBitmap  object  from  the  Jpeg  or  DBL  file  named  filename, 
alpha  filename  indicates  a  MSK  file  to  be  used  as  an  alpha  mask  for  a  Jpeg  image. 

Nota:  We  can  only  deal  with  baseline  (frame  0)  jpegs,  no  baseline  optimized  or  progressive  scan 
jpegs! 


SWFBitmap  has  the  following  methods  :  swfbitmap->getwidth()  and  swfbitmap->getheight(). 
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You  can’t  import  png  images  directly,  though-  have  to  use  the  png2dbl  utility  to  make  a  dbl  ("define  bits 
lossless")  file  from  the  png.  The  reason  for  this  is  that  I  don’t  want  a  dependency  on  the  png  library  in 
ming-  autoconf  should  solve  this,  but  that’s  not  set  up  yet. 

Ejemplo  1.  Import  PNG  files 

<?php 

$s  =  new  SWFShapeO; 

$f  =  $s->addFill (new  SWFBitmap ( "png . dbl " ) ) ; 

$s->setRightFill ( $ f )  ; 

$s->drawLine (32,  0); 

$s->drawLine (0,  32); 

$s->drawLine (-32,  0) ; 

$s->drawLine  (0,  -32); 

$m  =  new  SWFMovie ( ) ; 

$m->setDimension ( 32 ,  32); 

$m->add ($s) ; 

header ( ' Content-type :  application/x-shockwave-f lash' ) ; 

$m->output ( ) ; 

?> 


And  you  can  put  an  alpha  mask  on  a  jpeg  fill. 

Ejemplo  2.  swfbitmap()  example 

<?php 

$s  =  new  SWFShapeO; 

//  .msk  file  generated  with  "gif2mask"  utility 

$f  =  $s->addFill (new  SWFBitmap ( "alphaf ill . jpg" ,  "alphafill .msk") ) ; 
$s->setRightFill ( $  f ) ; 

$s->drawLine ( 64 0 ,  0) ; 

$s->drawLine (0,  480); 

$s->drawLine (-640,  0); 

$s->drawLine (0,  -480); 

$c  =  new  SWFShapeO; 

$c->setRightFill ( $c->addFill ( 0x99,  0x99,  0x99)); 

$c->drawLine  (40,  0); 

$c->drawLine  ( 0 ,  40); 

$c->drawLine (-40,  0); 

$c->drawLine (0,  -40); 

$m  =  new  SWFMovie ( ) ; 

$m->setDimension ( 640,  480); 
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$m->setBackground ( Oxcc,  Oxcc,  Oxcc) ; 

//  draw  checkerboard  background 
for($y=0;  $y<480;  $y+=40) 

{ 

for($x=0;  $x<640;  $x+=80) 

{ 

$i  =  $m->add($c); 

$i->moveTo ( $x,  $y) ; 

} 


$y+=4  0 ; 

for($x=40;  $x<640;  $x+=80) 

{ 

$i  =  $m->add($c); 

$i->moveTo ( $x,  $y) ; 

} 

} 

$m->add ($s) ; 

header ( ' Content-type :  application/x-shockwave-f lash' ) ; 
$m->output  ( ) ; 


SWFBitmap->getWidth  (unknown) 


Returns  the  bitmap’s  width. 


int  swfbitmap->getwidth  () 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


swfbitmap->getwidth()  returns  the  bitmap’s  width  in  pixels. 
See  also  swfbitmap->getheight(). 
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SWFBitmap->getHeight  (unknown) 


Ming  (flash) 


Returns  the  bitmap’s  height. 


int  swfbitmap->getheight  () 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


swfbitmap->getheight()  returns  the  bitmap’s  height  in  pixels. 
See  also  swfbitmap->getwidth(). 


SWFFill  (PHP  4  >=  4.0.5) 


Loads  SWFFill  object 

The  swffill()  object  allows  you  to  transform  (scale,  skew,  rotate)  bitmap  and  gradient  fills.  swffill() 
objects  are  created  by  the  swfshape->addfill()  methods. 

SWFFill  has  the  following  methods  :  swffill->moveto()  and  swffill->scaleto(),  swffill->rotateto(), 
swffill->skewxto()  and  swffill->skewyto(). 


SWFFill->moveTo  (unknown) 


Moves  fill  origin 


void  swf f ill->moveto  (int  x,  int  y) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


645 


Ming  (flash) 


swffill->moveto()  moves  fill’s  origin  to  (x,y)  in  global  coordinates. 


SWFFill->scaleTo  (unknown) 


Sets  fill’s  scale 


void  swf f ill->scaleto  (int  x,  int  y) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


swffill->scaleto()  sets  fill’s  scale  to  x  in  the  x-direction,  y  in  the  y-direction. 


SWFFill->rotateTo  (unknown) 


Sets  fill’s  rotation 


void  swffill->rotateto  (float  degrees ) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


swffill->rotateto()  sets  fill’s  rotation  to  degrees  degrees. 


SWFFill->skewXTo  (unknown) 


Sets  fill  x-skew 


void  swf f ill->skewxto  (float  x) 
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Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


swffill->skewxto()  sets  fill  x-skew  to  x.  For  x  is  1.0,  it  is  a  is  a  45-degree  forward  slant.  More  is  more 
forward,  less  is  more  backward. 


SWFFill->skewYTo  (unknown) 


Sets  fill  y-skew 


void  swf f ill->skewyto  (float  y) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


swffill->skewyto()  sets  fill  y-skew  to  y.  For  y  is  1.0,  it  is  a  is  a  45-degree  upward  slant.  More  is  more 
upward,  less  is  more  downward. 


SWFMorph  (PHP  4  >=4.0.5) 


Creates  a  new  SWFMorph  object. 


new  swfmorph  ( ) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 
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swfmorph()  creates  a  new  SWFMorph  object. 

Also  called  a  "shape  tween".  This  thing  lets  you  make  those  tacky  twisting  things  that  make  your 
computer  choke.  Oh,  joy! 

The  methods  here  are  sort  of  weird.  It  would  make  more  sense  to  just  have  newSWFMorph(shapel, 
shape2);,  but  as  things  are  now,  shape2  needs  to  know  that  it’s  the  second  part  of  a  morph.  (This,  because 
it  starts  writing  its  output  as  soon  as  it  gets  drawing  commands-  if  it  kept  its  own  description  of  its  shapes 
and  wrote  on  completion  this  and  some  other  things  would  be  much  easier.) 

SWFMorph  has  the  following  methods  :  swfmorph->getshapel()  and  swfmorph->getshapel(). 

This  simple  example  will  morph  a  big  red  square  into  a  smaller  blue  black-bordered  square. 

Ejemplo  1.  swfmorph()  example 

<?php 

$p  =  new  SWFMorph ( ) ; 

$s  =  $p->getShapel ( )  ; 

$s->setLine(0,0,0,0)  ; 

/*  Note  that  this  is  backwards  from  normal  shapes  (left  instead  of  right) . 

I  have  no  idea  why,  but  this  seems  to  work. .  */ 

$s->setLeftFill ($s->addFill (Oxff ,  0,  0)); 

$s->movePenTo (-1000,-1000) ; 

$s->drawLine  (2000,  0) ; 

$s->drawLine  (0,  2000) ; 

$s->drawLine (-2000, 0) ; 

$s->drawLine  (0, -2000) ; 

$s  =  $p->getShape2(); 

$s->setLine  (60, 0,0,0)  ; 

$s->setLeftFill ($s->addFill  (0,  0,  Oxff)); 

$s->movePenTo  (0,-1000) ; 

$s->drawLine (1000, 1000) ; 

$s->drawLine (-1000, 1000) ; 

$s->drawLine (-1000,-1000) ; 

$s->drawLine (1000,-1000) ; 

$m  =  new  SWFMovie ( ) ; 

$m-> set Dimens ion (3000,2000) ; 

$m->setBackground ( Oxf f ,  Oxff,  Oxff); 

$i  =  $m->add($p); 

$i->moveTo (1500, 1000) ; 

for($r=0.0;  $r<=1.0;  $r+=0.1) 

{ 

$i->setRatio  ( $ r ) ; 

$m->nextFrame () ; 

} 
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header ( ' Content-type :  application/x-shockwave-f lash' 
$m->output ( ) ; 


Ming  (flash) 


?> 


SWFMorph->getshape1  (unknown) 


Gets  a  handle  to  the  starting  shape 


mixed  swfmorph->getshapel  () 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


swfmorph->getshapel()  gets  a  handle  to  the  morph’s  starting  shape.  swfmorph->getshapel()  returns 
an  swfshape')  object. 


SWFMorph->getshape2  (unknown) 


Gets  a  handle  to  the  ending  shape 


mixed  swfmorph->getshape2  () 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


swfmorph->getshape2()  gets  a  handle  to  the  morph’s  ending  shape.  swfmorph->getshape2()  returns  an 
swfshape))  object. 
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SWFText  (PHP  4  >=  4.0.5) 


Ming  (flash) 


Creates  a  new  SWFText  object. 


new  swftext  ( ) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


swftext()  creates  a  new  SWFText  object,  fresh  for  manipulating. 

SWFText  has  the  following  methods  :  swftext->setfont(),  swftext->setheight(),  swftext->setspacing(), 
swftext->setcolor(),  swftext->moveto(),  swftext->addstring()  and  swftext->getwidth(). 

This  simple  example  will  draw  a  big  yellow  "PHP  generates  Flash  with  Ming"  text,  on  white 
background. 

Ejemplo  1.  swftextQ  example 


<?php 

$f  =  new  SWFFont ( "Techno . fdb" ) ; 

$t  =  new  SWFText 0 ; 

$t->setFont ( $  f ) ; 

$t->moveTo (200,  2400); 

$t->setColor ( Oxf f ,  Oxff,  0); 

$t->setHeight (1200) ; 

$t->addString ( "PHP  generates  Flash  with  Ming!!"); 

$m  =  new  SWFMovie ( ) ; 

$m->setDimension (5400,  3600); 

$m->add ( $t )  ; 

header ( ' Content-type :  application/x-shockwave-f lash' ) ; 
$m->output ( ) ; 

?> 
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SWFText->setFont  (unknown) 


Sets  the  current  font 


void  swftext->setfont  (string  font) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


swftext->setfont()  sets  the  current  font  to  font. 


SWFText->setHeight  (unknown) 


Sets  the  current  font  height 


void  swftext->setheight  (int  height) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


swftext->setheight()  sets  the  current  font  height  to  height.  Default  is  240. 


SWFText->setSpacing  (unknown) 

Sets  the  current  font  spacing 

void  swftext->setspacing  (float  spacing) 
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Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


swftext->setspacing()  sets  the  current  font  spacing  to  spacingspacing.  Default  is  1.0.  0  is  all  of  the 
letters  written  at  the  same  point.  This  doesn’t  really  work  that  well  because  it  inflates  the  advance  across 
the  letter,  doesn’t  add  the  same  amount  of  spacing  between  the  letters.  I  should  try  and  explain  that 
better,  prolly.  Or  just  fix  the  damn  thing  to  do  constant  spacing.  This  was  really  just  a  way  to  figure  out 
how  letter  advances  work,  anyway..  So  nyah. 


SWFText->setColor  (unknown) 


Sets  the  current  font  color 


void  swftext->setcolor  (int  red, 


int  green, 


int  blue 


int  a] ) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


swftext->setspacing()  changes  the  current  text  color.  Default  is  black.  I  think.  Color  is  represented  using 
the  RGB  system. 


SWFText->moveTo  (unknown) 


Moves  the  pen 


void  swftext->moveto  (int  x,  int  y) 


652 


Ming  (flash) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


swftext->moveto()  moves  the  pen  (or  cursor,  if  that  makes  more  sense)  to  (x,y)  in  text  object’s 
coordinate  space.  If  either  is  zero,  though,  value  in  that  dimension  stays  the  same.  Annoying,  should  be 
fixed. 


SWFText->addString  (unknown) 


Draws  a  string 


void  swftext->addstring  (string  string) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


swftext->addstring()  draws  the  string  string  at  the  current  pen  (cursor)  location.  Pen  is  at  the 
baseline  of  the  text;  i.e.,  ascending  text  is  in  the  -y  direction. 


SWFText->getWidth  (unknown) 


Computes  string’s  width 


void  swftext->addstring  (string  string) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 
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swftext->addstring()  returns  the  rendered  width  of  the  string  string  at  the  text  object’s  current  font, 
scale,  and  spacing  settings. 


SWFFont  (PHP  4  >=  4.0.5) 

Loads  a  font  definition 


new  swffont  (string  filename) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


If  filename  is  the  name  of  an  FDB  file  (i.e.,  it  ends  in  ".fdb"),  load  the  font  definition  found  in  said 
file.  Otherwise,  create  a  browser-defined  font  reference. 

FDB  ("font  definition  block")  is  a  very  simple  wrapper  for  the  SWF  DefineFont2  block  which  contains  a 
full  description  of  a  font.  One  may  create  FDB  files  from  SWT  Generator  template  files  with  the 
included  makefdb  utility-  look  in  the  util  directory  off  the  main  ming  distribution  directory. 

Browser-defined  fonts  don’t  contain  any  information  about  the  font  other  than  its  name.  It  is  assumed 
that  the  font  definition  will  be  provided  by  the  movie  player.  The  fonts  _serif,  _sans,  and  typewriter 
should  always  be  available.  For  example: 

<?php 

$f  =  newSWFFont ( "_sans " ) ; 

?> 

will  give  you  the  standard  sans-serif  font,  probably  the  same  as  what  you’d  get  with  <f  ont 

name="sans-serif  ">  in  HTML. 

swffont()  returns  a  reference  to  the  font  definition,  for  use  in  the  SWFText->setFont()  and  the 
SWFTextField->setFont()  methods. 

SWFFont  has  the  following  methods  :  swffont->getwidth(). 


swffont->getwidth  (unknown) 


Returns  the  string’s  width 
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int  swf font->getwidth  (string  string) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


swffont->getwidth( )  returns  the  string  string’s  width,  using  font’s  default  scaling.  You’ll  probably 
want  to  use  the  SWFText()  version  of  this  method  which  uses  the  text  object’s  scale. 


SWFTextField  (PHP  4  >=  4.0.5) 

Creates  a  text  field  object 

new  swftextfield  ([int  flags]) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


swftextfieldO  creates  a  new  text  field  object.  Text  Fields  are  less  flexible  than  swftextj)  objects-  they 
can’t  be  rotated,  scaled  non-proportionally,  or  skewed,  but  they  can  be  used  as  form  entries,  and  they  can 
use  browser-defined  fonts. 

The  optional  flags  change  the  text  field’s  behavior.  It  has  the  following  possibles  values  : 

•  SWFTEXTFIELD_NOEDIT  indicates  that  the  field  shouldn’t  be  user-editable 

•  SWFTEXTFIELD_PASSWORD  obscures  the  data  entry 

•  S  WFTEXTFIELD_DR AWB OX  draws  the  outline  of  the  textfield 

•  SWFTEXTFIELD_MULTILINE  allows  multiple  lines 

•  SWFTEXTFIELD_WORDWRAP  allows  text  to  wrap 

•  SWFTEXTFIELD_NOSELECT  makes  the  field  non-selectable 
Flags  are  combined  with  the  bitwise  OR  operation.  For  example, 

<?php 

$t  =  newSWFTextField ( SWFTEXTFIELD_P AS SWORD  |  SWFTEXTFIELD_NOEDIT) ; 
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?> 

creates  a  totally  useless  non-editable  password  field. 

SWFTextField  has  the  following  methods  :  swftextfield->setfont(),  swftextfield->setbounds(), 
swftextfield->align(),  swftextfield->setheight(),  swftextfield->setleftmargin(), 
swftextfield->setrightmargin(),  swftextfield->setmargins(),  swftextfield->setindentation(), 
swftextfield->setlinespacing(),  swftextfield->setcolor(),  swftextfield->setname()  and 
swftextfield->addstring(). 


SWFTextField->setFont  (unknown) 


Sets  the  text  field  font 


void  swftextf ield->setfont  (string  font) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


swftextfield->setfont()  sets  the  text  field  font  to  the  [browser-defined?]  font  font. 


SWFTextField->setbounds  (unknown) 


Sets  the  text  field  width  and  height 


void  swftextf ield->setbounds  (int  width,  int  height) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


swftextfield->setbounds()  sets  the  text  field  width  to  width  and  height  to  height.  If  you  don’t  set  the 
bounds  yourself,  Ming  makes  a  poor  guess  at  what  the  bounds  are. 
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SWFTextField->align  (unknown) 


Ming  (flash) 


Sets  the  text  field  alignment 


void  swftextf ield->align  (int  alignement) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


swftextfield->align()  sets  the  text  field  alignment  to  alignement.  Valid  values  for  alignement  are 
:  SWFTEXTFIELD_ALIGN_LEFT,  SWFTEXTFIELD_ALIGN_RIGHT, 
SWFTEXTFIELD_ALIGN_CENTER  and  SWFTEXTFIELD_ALIGN_JUSTIFY. 


SWFTextField->setHeight  (unknown) 

Sets  the  font  height  of  this  text  field  font. 

void  swftextf ield->setheight  (int  height) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


swftextfield->setheight()  sets  the  font  height  of  this  text  field  font  to  the  given  height  height.  Default 
is  240. 


SWFTextField->setLeftMargin  (unknown) 


Sets  the  left  margin  width  of  the  text  field. 


void  swftextf ield->setleftmargin  (int  width) 
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Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


swftextfield->setleftmargin()  sets  the  left  margin  width  of  the  text  field  to  width.  Default  is  0. 


SWFTextField->setrightMargin  (unknown) 


Sets  the  right  margin  width  of  the  text  field. 


void  swftextf ield->setrightmargin  (int  width) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


swftextfield->setrightmargin()  sets  the  right  margin  width  of  the  text  field  to  width.  Default  is  0. 


SWFTextField->setMargins  (unknown) 


Sets  the  margins  width  of  the  text  field. 


void  swftextf ield->setmargins  (int  left,  int  right) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


swftextfield->setmargins()  set  both  margins  at  once,  for  the  man  on  the  go. 
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SWFTextField->setindentation  (unknown) 


Ming  (flash) 


Sets  the  indentation  of  the  first  line. 


void  swftextf ield->setindentation  (int  width) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


swftextfield->setindentation()  sets  the  indentation  of  the  first  line  in  the  text  field,  to  width. 


SWFTextField->setl_ineSpacing  (unknown) 


Sets  the  line  spacing  of  the  text  field. 


void  swftextf ield->setlinespacing  (int  height) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


swftextfield->setlinespacing()  sets  the  line  spacing  of  the  text  field  to  the  height  of  height.  Default  is 
40. 


SWFTextField->setcolor  (unknown) 


Sets  the  color  of  the  text  field. 


void  swftextfield->setcolor  (int  red,  int  green,  int  blue  [,  int  a]) 
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Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


swftextfield->setcolor()  sets  the  color  of  the  text  field.  Default  is  fully  opaque  black.  Color  is 
represented  using  RGB  system. 


SWFTextField->setname  (unknown) 


Sets  the  variable  name 


void  swftextf ield->setname  (string  name) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


swftextfield->setname()  sets  the  variable  name  of  this  text  field  to  name,  for  form  posting  and  action 
scripting  purposes. 


SWFTextField->addstring  (unknown) 

Concatenates  the  given  string  to  the  text  field 

void  swftextf ield->addstring  (string  string) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


swftextfield->setname()  concatenates  the  string  string  to  the  text  field. 
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Ming  (flash) 


Creates  a  movie  clip  (a  sprite) 


new  swf sprite  () 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


swfspriteO  are  also  known  as  a  "movie  clip",  this  allows  one  to  create  objects  which  are  animated  in 
their  own  timelines.  Hence,  the  sprite  has  most  of  the  same  methods  as  the  movie. 

swfspriteO  has  the  following  methods  :  swfsprite->add(),  swfsprite->remove(), 
swfsprite->nextframe()  and  swfsprite->setframes(). 

This  simple  example  will  spin  gracefully  a  big  red  square. 

Ejemplo  1.  swfspriteO  example 

<?php 

$s  =  new  SWFShape () ; 

$s->setRightFill ( $s->addFill ( Oxf f ,  0,  0) ) ; 

$s->movePenTo (-500,-500) ; 

$s->drawLineTo (500,-500) ; 

$s->drawLineTo (500, 500) ; 

$s->drawLineTo (-500, 500 ) ; 

$s->drawLineTo (-500, -500) ; 

$p  =  new  SWFSprite (); 

$i  =  $p->add($s); 

$p->nextFrame () ; 

$i->rotate  (15) ; 

$p->nextFrame () ; 

$i->rotate  (15) ; 

$p->nextFrame () ; 

$i->rotate  (15) ; 

$p->nextFrame () ; 

$i->rotate  (15) ; 

$p->nextFrame () ; 

$i->rotate  (15) ; 

$p->nextFrame () ; 

$m  =  new  SWFMovie ( ) ; 

$i  =  $m->add ( $p) ; 

$i->moveTo (1500, 1000) ; 
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$i->setName ( "blah" ) ; 

$m->setBackground ( Oxf f ,  Oxff,  Oxff) ; 

$m-> set Dimens ion (3000,2000) ; 

header ( ' Content-type :  application/x-shockwave-f lash' ) ; 
$m->output ( ) ; 


SWFSprite->add  (unknown) 


Adds  an  object  to  a  sprite 


void  swf sprite->add  (ressource  object) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


swfsprite->add()  adds  a  swfshapej),  a  swfbutton3,  a  swftextj),  a  swfaction()  or  a  swfspriteO  object. 

For  displayable  types  (swfshape)),  swfbuttonO,  swftextj),  swfaction')  or  swfspriteO),  this  returns  a 
handle  to  the  object  in  a  display  list. 


SWFSprite->remove  (unknown) 


Removes  an  object  to  a  sprite 


void  swf sprite->remove  (ressource  object) 
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Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


swfsprite->remove()  remove  a  swfshape'),  a  swtbutton '),  a  swftextO,  a  swfaction ')  or  a  swtsprite') 
object  from  the  sprite. 


SWFSprite->setframes  (unknown) 

Sets  the  total  number  of  frames  in  the  animation. 


void  swf sprite->setf rames  (int  numberof frames) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


swfsprite->setframes()  sets  the  total  number  of  frames  in  the  animation  to  numberof  frames. 


SWFSprite->nextframe  (unknown) 


Moves  to  the  next  frame  of  the  animation. 


void  swf sprite->nextf rame  () 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


swfsprite->setframes()  moves  to  the  next  frame  of  the  animation. 
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Ming  (flash) 


Creates  a  new  Button. 


new  swfbutton  ( ) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


swfbuttonO  creates  a  new  Button.  Roll  over  it,  click  it,  see  it  call  action  code.  Swank. 

SWFButton  has  the  following  methods  :  swfbutton->addshape(),  swfbutton->setup(), 
swfbutton->setover()  swfbutton->setdown(),  swfbutton->sethit()  swfbutton->setaction()  and 
swfbutton->addaction() . 

This  simple  example  will  show  your  usual  interactions  with  buttons  :  rollover,  rollon,  mouseup, 
mousedown,  noaction. 

Ejemplo  1.  swfbutton()  example 

<?php 

$f  =  new  SWFFont ( "_serif " ) ; 

$p  =  new  SWFSpriteO; 

function  label ($string) 

{ 

global  $f; 

$t  =  new  SWFTextField ( ) ; 

$t->setFont  ( $ f ) ; 

$t->addString ($string) ; 

$t->setHeight  (200) ; 

$t->setBounds (3200, 200) ; 
return  $t; 

} 

function  addLabel ( $string) 

{ 

global  $p; 

$i  =  $p->add ( label ( $string) ) ; 

$p->nextFrame ( ) ; 

$p->remove ( $ 1 ) ; 

} 
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$p->add (new  SWFAction ( " stop  ();")); 
addLabel ( "NO  ACTION"); 
addLabel ( " SWFBUTTON_MOUSEUP " ) ; 
addLabel ( " SWFBUTTON_MOUSEDOWN" ) ; 
addLabel ( " SWFBUTTON_MOUSEOVER" ) ; 
addLabel ( "SWFBUTTON_MOUSEOUT" ) ; 
addLabel ( " SWFBUTTON_MOUSEUPOUTSIDE" ) ; 
addLabel ( " SWFBUTTON_DRAGOVER" ) ; 
addLabel ( "SWFBUTTON_D RAGOUT " ) ; 

function  rect ($r,  $g,  $b) 

| 

$s  =  new  SWFShapeO; 

$s->setRightFill ( $s->addFill ( $r ,  $g,  $b) ) ; 

$s->drawLine (600,0) ; 

$s->drawLine (0, 600) ; 

$s->drawLine (-600, 0 ) ; 

$s->drawLine (0,-600) ; 


return  $s; 

} 


$b  =  new  SWFButton ( ) ; 

$b->addShape (rect (Oxff ,  0,  0),  SWFBUTTON_UP  I  SWFBUTTON_HIT) ; 
$b->addShape (rect (0,  Oxff,  0),  SWFBUTTON_OVER) ; 

$b->addShape (rect (0,  0,  Oxff),  SWFBUTTON_DOWN) ; 

$b->addAction (new  SWFAction ( " set Target ( ' /label ' ) ;  gotoFrame ( 1 ) ; " ) , 
SWFBUTTON_MOUSEUP ) ; 

$b->addAction (new  SWFAction ( " set Target ( ' /label ' ) ;  gotoFrame (2 ) ; " ) , 
SWFBUTTON_MOUSEDOWN) ; 

$b->addAction (new  SWFAction ( "setTarget ( ' /label' ) ;  gotoFrame (3) ; " ) , 
SWF BUT TON_MOUSE OVER) ; 

$b->addAction (new  SWFAction ( "setTarget ( ' /label ' ) ;  gotoFrame ( 4) ; " ) , 
SWFBUTTON_MOUSEOUT ) ; 

$b->addAction (new  SWFAction ( "setTarget ( ' /label ' ) ;  gotoFrame ( 5 ) ; " ) , 
SWFBUTTON_MOUSEUPOUTS IDE ) ; 

$b->addAction (new  SWFAction ( "setTarget ( ' /label ' ) ;  gotoFrame ( 6 ) ; " ) , 
SWFBUTTON_DRAGOVER) ; 


$b->addAction (new  SWFAction ( "setTarget ( ' /label ' ) ;  gotoFrame ( 7 ) ; " ) , 
SWFBUTTON_D RAGOUT) ; 


$m  =  new  SWFMovie ( ) ; 

$m-> set Dimens ion (4000,3000) ; 

$i  =  $m->add($p); 
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$i->setName ( "label" ) ; 

$i->moveTo (400, 1900) ; 

$i  =  $m->add ( $b) ; 

$i->moveTo (400, 900) ; 

header ( ' Content -type :  application/ x-shockwave-f lash' ) ; 
$m->output ( ) ; 


This  simple  example  will  enables  you  to  drag  draw  a  big  red  button  on  the  windows.  No  drag-and-drop, 
just  moving  around. 

Ejemplo  2.  swfbutton->addaction()  example 

<?php 

$s  =  new  SWFShapeO; 

$s->setRightFill ( $s->addFill ( Oxf f ,  0,  0) ) ; 

$s->drawLine (1000, 0) ; 

$s->drawLine  (0,  1000) ; 

$s->drawLine  (-1000, 0)  ; 

$s->drawLine  (0, -1000) ; 

$b  =  new  SWFButton ( ) ; 

$b->addShape ($S,  SWFBUTTON_HIT  |  SWFBUTTON_UP  |  SWFBUTTON_DOWN  |  SWFBUTTON_OVER) ; 

$b->addAction (new  SWFAction ( " startDrag ( ' /test ' ,  0);"),  //  '0'  means  don't  lock  to  mouse 

S WF BUT TON_MOUSE DOWN)  ; 

$b->addAction (new  SWFAction ( "stopDrag ();"), 

SWFBUTTON_MOUSEUP  |  SWFBUTTON_MOUSEUPOUTS IDE ) ; 

$p  =  new  SWFSprite ( ) ; 

$p->add ( $b) ; 

$p->nextFrame () ; 

$m  =  new  SWFMovie ( ) ; 

$i  =  $m->add($p); 

$i->setName ( ' test' ) ; 

$i->moveTo (1000, 1000) ; 

header ( ' Content-type :  application/x-shockwave-f lash' ) ; 

$m->output  ( ) ; 

?> 
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Adds  a  shape  to  a  button 


void  swfbutton->addshape  (ressource  shape,  int  flags) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


swfbutton->addshape()  adds  the  shape  shape  to  this  button.  The  following  flags’  values  are  valid: 
SWFBUTTONJJP,  SWFBUTTON_OVER,  SWFBUTTON_DOWN  or  SWFBUTTON_HIT. 
SWFBUTTON_HIT  isn’t  ever  displayed,  it  defines  the  hit  region  for  the  button.  That  is,  everywhere  the 
hit  shape  would  be  drawn  is  considered  a  "touchable"  part  of  the  button. 


SWFbutton->setUp  (unknown) 

Alias  for  addShapefshape,  SWFBUTTONJJP) 

void  swfbutton->setup  (ressource  shape) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


swfbutton->setup()  alias  for  addShapef shape,  SWFBUTTON_UP). 
See  also  swfbutton->addshape()  and  SWFAction(). 


SWFbutton->setOver  (unknown) 


Alias  for  addShapefshape,  SWFBUTTON_OVER) 
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void  swfbutton->setover  (ressource  shape) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


swfbutton->setover()  alias  for  addShapef shape,  SWFBUTTON_OVER). 
See  also  swfbutton->addshape()  and  SWFAction(). 


SWFbutton->setdown  (unknown) 

Alias  for  addShape(shape,  SWFBUTTON_DOWN)) 

void  swfbutton->setdown  (ressource  shape) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


swfbutton->setdown()  alias  for  addShape(shape,  SWFBUTTON_DOWN). 
See  also  swfbutton->addshape()  and  SWFActionQ. 


SWFbutton->setHit  (unknown) 

Alias  for  addShapefshape,  SWFBUTTONJHIT) 

void  swfbutton->sethit  (ressource  shape) 
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Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


swfbutton->sethit()  alias  for  addShapef shape,  SWFBUTTON_HIT). 
See  also  swfbutton->addshape()  and  SWFAction(). 


SWFbutton->addAction  (unknown) 


Adds  an  action 


void  swfbutton->addaction 


(ressource  action, 


int  flags ) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


swfbutton->addaction()  adds  the  action  action  to  this  button  for  the  given  conditions.  The  following 
flags  are  valid:  SWFBUTTON_MOUSEOVER,  SWFBUTTON_MOUSEOUT, 
SWFBUTTON_MOUSEUP,  SWFBUTTON_MOUSEUPOUTSIDE,  SWFBUTTON_MOUSEDOWN, 
SWFBUTTON_DRAGOUT  and  SWFBUTTON_DRAGOVER. 

See  also  swfbutton->addshape()  and  SWFAction(). 


SWFbutton->setAction  (unknown) 


Sets  the  action 


void  swfbutton->setaction  (ressource  action) 
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Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


swfbutton->setaction()  sets  the  action  to  be  performed  when  the  button  is  clicked.  Alias  for 
addActionfshape,  SWFBUTTON_MOUSEUP).  action  is  a  swfaction '). 

See  also  swfbutton->addshape()  and  SWFAction(). 


SWFAction  (PHP  4  >=  4.0.5) 

Creates  a  new  Action. 


new  swfaction  (string  script) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


swfaction()  creates  a  new  Action,  and  compiles  the  given  script  into  an  SWFAction  object. 

The  script  syntax  is  based  on  the  C  language,  but  with  a  lot  taken  out-  the  SWF  bytecode  machine  is  just 
too  simpleminded  to  do  a  lot  of  things  we  might  like.  For  instance,  we  can’t  implement  function  calls 
without  a  tremendous  amount  of  hackery  because  the  jump  bytecode  has  a  hardcoded  offset  value.  No 
pushing  your  calling  address  to  the  stack  and  returning-  every  function  would  have  to  know  exactly 
where  to  return  to. 

So  what’s  left?  The  compiler  recognises  the  following  tokens: 

•  break 

•  for 

•  continue 

•  if 

•  else 

•  do 

•  while 
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There  is  no  typed  data;  all  values  in  the  SWF  action  machine  are  stored  as  strings.  The  following 
functions  can  be  used  in  expressions: 


time() 

Returns  the  number  of  milliseconds  (?)  elapsed  since  the  movie  started. 

random(seed) 

Returns  a  pseudo-random  number  in  the  range  0-seed. 

length(expr) 

Returns  the  length  of  the  given  expression. 

int(number) 

Returns  the  given  number  rounded  down  to  the  nearest  integer. 

concat(expr,  expr) 

Returns  the  concatenation  of  the  given  expressions 


ord(expr) 

Returns  the  ASCII  code  for  the  given  character 

chr(num) 

Returns  the  character  for  the  given  ASCII  code 

substr(string,  location,  length) 

Returns  the  substring  of  length  length  at  location  location  of  the  given  string  string. 

Additionally,  the  following  commands  may  be  used: 
duplicateClip(clip,  name,  depth) 

Duplicate  the  named  movie  clip  (aka  sprite).  The  new  movie  clip  has  name  name  and  is  at  depth 
depth. 

removed  ipt  expr) 

Removes  the  named  movie  clip. 


trace(expr) 

Write  the  given  expression  to  the  trace  log.  Doubtful  that  the  browser  plugin  does  anything  with 
this. 

startDrag(target,  lock,  [left,  top,  right,  bottom]) 

Start  dragging  the  movie  clip  target.  The  lock  argument  indicates  whether  to  lock  the  mouse  (?) 
use  0  (false)  or  1  (true).  Optional  parameters  define  a  bounding  area  for  the  dragging. 
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stopDragQ 

Stop  dragging  my  heart  around.  And  this  movie  clip,  too. 

callFrame(expr) 

Call  the  named  frame  as  a  function. 
getURL(url,  target,  [method]) 

Load  the  given  url  into  the  named  target.  The  target  argument  can  be  a  frame  name  (I  think),  or  one 
of  the  magical  values  "_levelO"  (replaces  current  movie)  or  "_levell"  (loads  new  movie  on  top  of 
current  movie).  The  optional  method  argument  can  be  post  or  get  if  you  want  to  submit  variables 
back  to  the  server. 

loadMovie(url,  target) 

Same  as  above,  more  or  less.  Come  to  think  of  it,  I  don’t  quite  know  what  the  difference  is. 


nextFrame() 

Go  to  the  next  frame. 

prevFrame() 

Go  to  the  last  (or,  rather,  previous)  frame. 

play() 

Start  playing  the  movie. 

stop() 

Stop  playing  the  movie. 

toggleQuality() 

Toggle  between  high  and  low  quality. 

stopSoundsQ 

Stop  playing  all  sounds. 

gotoFrame(num) 

Go  to  frame  number  num.  Frame  numbers  start  at  0. 
gotoFrame(name) 

Go  to  the  frame  named  name.  Which  does  a  lot  of  good,  since  I  haven't  added  frame  labels  yet. 

setTarget(expr) 

Sets  the  context  for  action.  Or  so  they  say- 1  really  have  no  idea  what  this  does. 

And  there’s  one  weird  extra  thing.  The  expression  frameLoaded(num)  can  be  used  in  if  statements  and 
while  loops  to  check  if  the  given  frame  number  has  been  loaded  yet.  Well,  it’s  supposed  to,  anyway,  but 
I’ve  never  tested  it  and  I  seriously  doubt  it  actually  works.  You  can  just  use  /:framesLoaded  instead. 
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Movie  clips  (all  together  now-  aka  sprites)  have  properties.  You  can  read  all  of  them  (or  can  you?),  you 
can  set  some  of  them,  and  here  they  are: 

•  x 

•  y 

•  xScale 

•  yScale 

•  currentFrame  -  (read-only) 

•  totalFrames  -  (read-only) 

•  alpha  -  transparency  level 

•  visible  -  l=on,  0=off  (?) 

•  width  -  (read-only) 

•  height  -  (read-only) 

•  rotation 

•  target  -  (read-only)  (???) 

•  framesLoaded  -  (read-only) 

•  name 

•  dropTarget  -  (read-only)  (???) 

•  url  -  (read-only)  (???) 

•  highQuality  -  l=high,  0=low  (?) 

•  focusRect  -  (???) 

•  soundBufTime  -  (???) 

So,  setting  a  sprite’s  x  position  is  as  simple  as  /box .  x  =  100; .  Why  the  slash  in  front  of  the  box, 
though?  That’s  how  flash  keeps  track  of  the  sprites  in  the  movie,  just  like  a  unix  filesystem-  here  it  shows 
that  box  is  at  the  top  level.  If  the  sprite  named  box  had  another  sprite  named  biff  inside  of  it,  you’d  set  its 
x  position  with  /box/biff.x  =  100;.  At  least,  I  think  so;  correct  me  if  I’m  wrong  here. 

This  simple  example  will  move  the  red  square  across  the  window. 

Ejemplo  1.  swfactionO  example 

<?php 

$s  =  new  SWFShapeO; 

$f  =  $s->addFill (Oxff,  0,  0); 

$s->setRightFill ( $  f )  ; 

$s->movePenTo (-500,-500) ; 

$s->drawLineTo (500,-500) ; 

$s->drawLineTo  (500, 500) ; 

$s->drawLineTo (-500, 500 ) ; 

$s->drawLineTo (-500, -500) ; 
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$p  =  new  SWFSpriteO; 

$i  =  $p->add($s); 

$i->setDepth  (1) ; 

$p->nextFrame () ; 

for($n=0;  $n<5;  ++$n) 

{ 

$i->rotate  (-15) ; 

$p->nextFrame () ; 

} 

$m  =  new  SWFMovie ( ) ; 

$m->setBackground ( Oxf f ,  Oxff,  Oxff) ; 

$m-> set Dimens ion (6000, 4000) ; 

$i  =  $m->add($p); 

$i->setDepth  (1) ; 

$i->moveTo (-500, 2000) ; 

$i->setName ( "box" ) ; 

$m->add(new  SWFAct ion ( " /box . x  +=  3;")); 

$m->nextFrame () ; 

$m->add(new  SWFAction ( "gotoFrame ( 0 ) ;  play();")); 
$m->nextFrame () ; 

header ( ' Content-type :  application/x-shockwave-f lash' ) ; 
$m->output ( ) ; 


This  simple  example  tracks  down  your  mouse  on  the  screen. 

Ejemplo  2.  swfaction()  example 

<?php 

$m  =  new  SWFMovie ( ) ; 

$m-> set Rate (36.0) ; 

$m->setDimension ( 12 00 ,  800); 

$m->setBackground ( 0 ,  0,  0) ; 

/*  mouse  tracking  sprite  -  empty,  but  follows  mouse  so  we  can 
get  its  x  and  y  coordinates  */ 

$i  =  $m->add  (new  SWFSpriteO); 

$i->setName ( ' mouse' ) ; 

$m->add(new  SWFAction (" 

startDrag (' /mouse' ,  1);  /*  '1'  means  lock  sprite  to  the  mouse  */ 

") ) ; 
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/*  might  as  well  turn  off  antialiasing,  since  these  are  just  squares.  */ 

$m->add(new  SWFAction(" 
this. quality  =  0; 

" )  )  ; 

/*  morphing  box  */ 

$r  =  new  SWFMorph(); 

$s  =  $r->getShapel  ( ) ; 

/*  Note  this  is  backwards  from  normal  shapes.  No  idea  why.  */ 
$s->setLeftFill ($s->addFill (Oxff ,  Oxff,  Oxff ) ) ; 

$s->movePenTo (-40,  -40); 

$s->drawLine  (80,  0); 

$s->drawLine  (0,  80); 

$s->drawLine  (-80,  0) ; 

$s->drawLine (0,  —80) ; 

$s  =  $r->getShape2  ( ) ; 

$s->setLeftFill ($s->addFill (0x00,  0x00,  0x00) ) ; 

$s->movePenTo (-1,  -1); 

$s->drawLine  (2 ,  0); 

$s->drawLine  (0,  2); 

$s->drawLine (-2,  0); 

$s->drawLine  (0,  -2); 


/*  sprite  container  for  morphing  box  - 

this  is  just  a  timeline  w/  the  box  morphing  */ 

$box  =  new  SWFSpriteO; 

$box->add (new  SWFAction(" 
stop ( ) ; 

" )  > ; 

$i  =  $box->add ( $r ) ; 

for($n=0;  $n<=20;  ++$n) 

{ 

$i->setRatio ( $n/20 ) ; 

$box->nextFrame () ; 

} 


/*  this  container  sprite  allows  us  to  use  the  same  action  code  many  times  */ 

$cell  =  new  SWFSpriteO; 

$i  =  $cell->add ( $box) ; 

$i->setName ( ' box' ) ; 

$cell->add (new  SWFAction(" 
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setTarget ( ' box' ) ; 

/*  ...x  means  the  x  coordinate  of  the  parent,  i.e.  ( .  ,).x  */ 
dx  =  (/mouse. x  +  random(6)-3  -  ...x)/5; 
dy  =  (/mouse. y  +  random(6)-3  -  ...y)/5; 
gotoFrame ( int (dx*dx  +  dy*dy) ) ; 

" ) ) ; 

$cell->nextFrame ( ) ; 

$cell->add (new  SWFAction(" 

gotoFrame ( 0 )  ; 
play ( ) ; 

" ) ) ; 

$cell->nextFrame ( ) ; 


/*  finally,  add  a  bunch  of  the  cells  to  the  movie  */ 

for($x=0;  $x<12;  ++$x) 

{ 

for ( $y=0 ;  $y<8;  ++$y) 

{ 

$i  =  $m->add ( $cell ) ; 

$i->moveTo (100*$x+50,  100*$y+50) ; 

} 


$m->nextFrame () ; 

$m->add(new  SWFAction(" 

gotoFrame ( 1 ) ; 
play ( ) ; 

" )  )  ; 

header ( ' Content-type :  application/x-shockwave-f lash' ) ; 
$m->output  ( ) ; 


Same  as  above,  but  with  nice  colored  balls... 
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Ejemplo  3.  swfaction()  example 

<?php 

$m  =  new  SWFMovie ( ) ; 

$m->setDimension ( 11000 ,  8000); 

$m->setBackground (0x00,  0x00,  0x00); 

$m->add(new  SWFAction(" 

this. quality  =  0; 

/frames .visible  =  0; 
startDrag (' /mouse' ,  1); 

" ) )  ; 

//  mouse  tracking  sprite 
$t  =  new  SWFSpriteO; 

$i  =  $m->add($t); 

$i->setName ( ' mouse' ) ; 

$g  =  new  SWFGradient  () ; 

$g->addEntry  ( 0 ,  Oxff,  Oxff,  Oxff,  Oxff); 

$g->addEntry ( 0 . 1 ,  Oxff,  Oxff,  Oxff,  Oxff); 

$g->addEntry (0 . 5,  Oxff,  Oxff,  Oxff,  0x5f) ; 

$g->addEntry ( 1 . 0 ,  Oxff,  Oxff,  Oxff,  0); 

/ /  gradient  shape  thing 
$s  =  new  SWFShapeO; 

$f  =  $s->addFill ($g,  SWFFILL_RADIAL_GRADIENT) ; 
$f->scaleTo(0.03) ; 

$s->setRightFill ( $  f )  ; 

$s->movePenTo (-600,  -600); 

$s->drawLine (1200,  0); 

$s->drawLine  (0,  1200); 

$s->drawLine (-1200,  0); 

$s->drawLine  (0,  -1200); 

//  need  to  make  this  a  sprite  so  we  can  multColor  it 
$p  =  new  SWFSpriteO; 

$p->add ($s) ; 

$p->nextFrame () ; 

//  put  the  shape  in  here,  each  frame  a  different  color 
$q  =  new  SWFSpriteO; 

$q->add(new  SWFAction ( "gotoFrame (random ( 7 ) +1 ) ;  stop();")); 

$i  =  $q->add($p); 

$i->multColor ( 1 . 0 ,  1.0,  1.0); 

$q->nextFrame () ; 

$i->multColor ( 1 . 0 ,  0.5,  0.5); 

$q->nextFrame () ; 

$i->multColor  ( 1 . 0 ,  0.75,  0.5); 
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$q->nextFrame ( ) ; 


$i->mult Color (1.0, 
$q->nextFrame ()  ; 

1.0, 

0.5)  ; 

$i->multColor (0.5, 
$q->nextFrame () ; 

1.0, 

0.5)  ; 

$i->multColor (0.5, 
$q->nextFrame () ; 

0.5, 

1.0)  ; 

$i->mult Color (1.0, 
$q->nextFrame ( ) ; 

0.5, 

1.0)  ; 

//  finally,  this  one  contains  the  action  code 
$p  =  new  SWFSpriteO; 

$i  =  $p->add($q); 

$i->setName ( ' frames' ) ; 

$p->add(new  SWFAction(" 

dx  =  ( / :mousex-/ : lastx) /3  +  random ( 10 ) -5; 
dy  =  ( / :mousey-/ : lasty ) /3; 
x  =  / : mousex; 
y  =  / : mousey; 
alpha  =  100; 

" )  )  ; 

$p->nextFrame ()  ; 

$p->add(new  SWFAction(" 

this.x  =  x; 

this.y  =  y; 

this. alpha  =  alpha; 

x  +=  dx; 

y  +=  dy; 

dy  +=  3; 

alpha  -=  8; 

" ) )  ; 

$p->nextFrame () ; 

$p->add(new  SWFAction ( "prevFrame ( ) ;  play();")); 
$p->nextFrame () ; 

$i  =  $m->add($p); 

$i->setName ( ' frames' ) ; 

$m->nextFrame () ; 

$m->add(new  SWFAction (" 

lastx  =  mousex; 
lasty  =  mousey; 
mousex  =  /mouse. x; 
mousey  =  /mouse. y; 

++num; 
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if  (num  ==  11) 
num  =  1  ; 

removeClip ( ' char '  &  num); 

duplicateClip ( /frames ,  'char'  &  num,  num) ; 

" )  > ; 

$m->nextFrame ( )  ; 

$m->add (new  SWFAction ( "prevFrame ( ) ;  play ();")); 

header ( ' Content -type :  application/ x-shockwave-f lash' ) ; 
$m->output  ( ) ; 


This  simple  example  will  handles  keyboard  actions.  (You’ll  probably  have  to  click  in  the  window  to  give 
it  focus.  And  you’ll  probably  have  to  leave  your  mouse  in  the  frame,  too.  If  you  know  how  to  give 
buttons  focus  programatically,  feel  free  to  share,  won’t  you?) 

Ejemplo  4.  swfactionQ  example 


<?php 

/*  sprite  has  one  letter  per  frame  */ 

$p  =  new  SWFSpriteO; 

$p->add (new  SWFAction (" stop ();")) ; 

$chars  =  " abcdefghi jklmnopqrstuvwxyz " . 

"ABCDEFGHI JKLMNOPQRSTUVWXYZ" . 

"1234567890!@#$%A&* () _H — =/ [ ] {} I; 

$f  =  new  SWFFont ( "_sans " ) ; 

for($n=0;  $nremove ( $i ) ; 

$t  =  new  SWFTextField ( ) ; 

$t->setFont  ($f) ; 

$t->setHeight (240) ; 

$t->setBounds (600,240) ; 

$t->align ( SWFTEXTF IELD_ALIGN_CENTER) ; 
$t->addString  ( $ c ) ; 

$i  =  $p->add($t); 

$p->labelFrame ( $  c ) ; 

$p->nextFrame ( ) ; 

} 


/*  hit  region  for  button  -  the  entire  frame  */ 
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$s  =  new  SWFShapeO; 

$s->setFillStyleO ( $s->addSolidFill  (0,  0,  0,  0) ) ; 
$s->drawLine  ( 600 ,  0) ; 

$s->drawLine  (0,  400); 

$s->drawLine  (-600,  0); 

$s->drawLine  (0,  -400); 


/*  button  checks  for  pressed  key,  sends  sprite  to  the  right  frame  */ 

$b  =  new  SWFButton(); 

$b->addShape ($s,  SWFBUTTON_HIT) ; 

for($n=0;  $naddAction (new  SWFAction(" 

set Tar get ( ' / char' ) ; 
gotoFrame (' $c' ) ; 

"),  SWFBUTTON_KEYPRESS ($c) ) ; 

} 

$m  =  new  SWFMovie ( ) ; 

$m-> set Dimens ion (600,400) ; 

$i  =  $m->add($p); 

$i->setName ( ' char' ) ; 

$i->moveTo (0,80); 

$m->add ( $b) ; 

header ( ' Content-type :  application/x-shockwave-f lash' ) ; 

$m->output ( ) ; 


?> 
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Lll.  Miscelanea  de  funciones 


Estas  funciones  estan  colacadas  aquf  debido  a  que  no  parecen  ajustarse  a  ninguna  otra  categona. 
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connectionaborted  (php  3>=  3.0.7,  PHP  4  >=  4.0.0) 

Devuelve  true  si  el  cliente  esta  desconectado 

int  connection_aborted  (void  ) 


Devuelve  true  si  el  cliente  esta  desconectado.  Vea  la  descripcion  de  la  Gestion  de  la  Conexion  en  el 
capftulo  Caracteristicas  para  una  explicacion  completa. 


connection_status  (PHP  3>=  3.0.7,  PHP  4  >=  4.0.0) 

Devuelve  el  estado  de  la  conexion  en  un  campo  de  bits 

int  connection_status  (void  ) 


Devuelve  el  estado  de  la  conexion  en  un  campo  de  bits.  Vea  la  descripcion  de  la  Gestion  de  la  Conexion 
en  el  capftulo  Caracteristicas  para  una  explicacion  completa. 


connectiontimeout  (PHP  3>=  3.0.7,  4.0.0  -  4.0.4  only) 

Devuelve  true  si  el  script  ha  alcanzado  su  time  out 

int  connection_timeout  (void  ) 


Devuelve  true  si  el  script  ha  alcanzado  su  time  out.  Vea  la  descripcion  de  la  Gestion  de  la  Conexion  en 
el  capftulo  Caracteristicas  para  una  explicacion  completa. 


define  (PHP  3,  PHP  4  >=  4.0.0) 

Define  una  constante  con  nombre. 

int  define  (string  name,  mixed  value  [,  int  case_insensitive] ) 

Define  una  constante  con  nombre,  que  es  similar  a  una  variable,  excepto  que: 
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•  Las  constantes  no  tienen  un  sfmbolo  dolar  ’$’  precediendolas; 

•  Las  constantes  son  accesibles  desde  cualquier  lugar  sin  tener  en  cuenta  las  reglas  de  ambito  de  las 
variables. 

•  Las  constantes  no  pueden  ser  redefinidas  o  iniciadas  una  vez  que  han  sido  establecidas,  y 

•  Las  constantes  solo  pueden  evaluar  valores  escalares 


El  nombre  de  la  constante  se  da  en  name  (nombre);  el  valor  se  da  en  value  (valor). 

El  tercer  parametro  opcional  case_insensitive  tambien  se  encuentra  disponible.  Si  se  da  el  valor 
1,  la  constante  se  definira  no  dintinguiendo  mayusculas/minusculas.  El  comportamiento  por  defecto  es  si 
distinguir;  i.e.  CONSTANT  y  Constant  representan  valores  diferentes. 


Ejemplo  1.  Definicion  de  Constantes 


<?php 

define ( "CONSTANT" ,  "Hello  world."); 
echo  CONSTANT;  //  outputs  "Hello  world." 
?> 


defineO  devuelve  true  en  caso  de  exito  y  false  si  ocurre  un  error. 
Vease  tambien  defined ')  y  la  seccion  Constantes 


defined  (PHP  3,  PHP  4  >=  4.0.0) 

Comprueba  que  una  constante  con  nombre  dada  existe. 

int  defined  (string  name ) 

Devuelve  true  si  la  constante  con  nombre  dada  en  name  (nombre)  ha  sido  definida,  false  en  otro  caso. 
Vease  tambien  define))  y  la  seccion  Constantes 


die 


(unknown) 

Envfa  a  la  salida  un  mensaje  y  finaliza  el  script  actual 

void  die  (string  message) 
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Esta  construction  del  lenguaje  envfa  a  la  salida  un  mensaje  y  finaliza  la  ejecucion  del  script.  No  devuelve 
nada. 


Ejemplo  1.  Ejemplo  die 

<?php 

$filename  =  ' /path/to/data- f ile' ; 

$file  =  fopen ( $f ilename,  '  r' ) 

or  die  "unable  to  open  file  ( $f ilename )" ; 

?> 


eval 


(unknown) 

Evalua  una  cadena  de  caracteres  como  codigo  PHP 

void  eval  (string  code_str) 


eval()  evalua  la  cadena  de  caracteres  dada  en  code_str  como  codigo  PHP  Entre  otras  cosas,  esto 
puede  ser  util  para  almacenar  codigo  en  un  campo  de  texto  de  base  de  datos  para  una  ejecucion  posterior. 

Hay  algunos  aspectos  a  tener  en  cuenta  cuando  se  utiliza  eval().  Recuerde  que  la  cadena  de  caracteres 
pasada  debe  ser  codigo  PHP  valido,  incluyendo  aspectos  como  sentencias  de  termination  con  un  punto  y 
coma  para  que  el  parser  no  finalice  en  la  lfnea  despues  de  eval(),  y  secuencias  de  formato  correctas  en 

code_str. 

Recuerde  tambien  que  las  variables  a  las  que  se  les  da  valor  en  eval()  retendran  estos  valores 
posteriormente  en  el  script  principal. 


Ejemplo  1.  Ejemplo  eval()  -  fusion  en  un  unico  texo 

<?php 

$string  =  ' cup' ; 

$name  =  'coffee'; 

$str  =  'This  is  a  $string  with  my  $name  in  it.<br>'; 
echo  $str; 

eval (  "\$str  =  \"$str\"; "  ); 
echo  $str; 

?> 


El  ejemplo  anterior  mostrara; 
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This  is  a  $string  with  my  $name  in  it. 
This  is  a  cup  with  my  coffee  in  it. 


Misc. 


exit 


(unknown) 


Finaliza  el  script  actual 


void  exit (void) ; 


Esta  construccion  del  lenguaje  finaliza  la  ejecucion  del  script.  No  devuelve  nada. 


get_browser  (PHP  3,  PHP  4  >=  4.0.0) 

Informa  sobre  lo  que  es  capaz  de  hacer  el  navegador  (browser)  del  usuario. 

object  get_browser  ( [string  user_agent] ) 


get_browser()  intenta  determinar  las  caracterfsticas  del  navegador  del  usuario.  Para  ello  consulta  el 
fichero  de  informacion  del  navegador,  browscap .  ini.  Por  defecto,  se  utiliza  el  valor  de 
$HTTP_USER_AGENT;  sin  embargo,  puede  alterar  esto  (i.e.,  consultando  otra  informacion  del 
navegador)  pasando  el  parametro  opcional  user_agent  a  get_browser(). 

La  informacion  se  devuelve  en  un  objto,  que  contendra  varios  elementos  de  datos  que  representan,  por 
ejemplo,  los  numeros  de  version  (mayor  y  menor)  del  navegador  y  la  cadena  ID;  valores  TRUE/false  para 
caracterfsticas  como  los  marcos,  JavaScript,  y  cookies;  etc. 

browscap .  ini  contiene  informacion  de  muchos  navegadores,  depende  de  las  actualizaciones  del 
usuario  para  mantener  la  base  de  datos  actualizada.  El  formato  del  fichero  es  claramente  auto-explicativo. 

El  ejemplo  siguiente  muestra  como  se  puede  listar  toda  la  informacion  disponible  recuperada  del 
navegador  del  usuario. 

Ejemplo  1.  ejemplo  get_browser() 

<?php 

function  list_array (  $array  )  { 

while  (  list  (  $key,  $value  )  =  each  (  $array  )  )  { 

$str  .=  "<b>$key : </b>  $value<br>\n" ; 

} 

return  $str; 
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} 

echo  " $HTTP_USER_AGENT<hr>\n" ; 
$browser  =  get_browser ( ) ; 
echo  list_array (  (array)  $browser  ); 
?> 


La  salida  del  script  anterior  deberfa  paracerse  a  esto: 

Mozilla/4.5  [en]  (Xll;  U;  Linux  2.2.9  i586)<hr> 

<b>browser_name_pattern : </b>  Mozilla/ 4\ . 5 . *<br> 

<b>parent : </b>  Netscape  4 . 0<br> 

<b>platform: </b>  Unknown<br> 

<b>ma jorver : </b>  4<br> 

<b>minorver : </b>  5<br> 

<b>browser : </b>  Netscape<br> 

<b>version : </b>  4<br> 

<b>f rames : </b>  l<br> 

<b>tables : </b>  l<br> 

<b>cookies : </b>  l<br> 

<b>backgroundsounds : </b>  <br> 

<b>vbscript : </b>  <br> 

<b> javascript : </b>  l<br> 

<b> javaapplets : </b>  l<br> 

<b>activexcontrols : </b>  <br> 

<b>beta:</b>  <br> 

<b>crawler : </b>  <br> 

<b>authenticodeupdate : </b>  <br> 

<b>msn:</b>  <br> 

Para  conseguir  esto,  su  opcion  de  fichero  de  configuration  browscap  debe  apuntar  a  la  correcta 
localization  del  fichero  browscap .  ini. 

Para  mas  information  (incluyendo  localizaciones  desde  las  que  puede  obtener  un  fichero 
browscap .  ini),  consulte  las  FAQ  sobre  PHP  en  http://www.php.net/FAQ.html 
(http  ://w  w  w.php  .net/FAQ  .php) . 

Nota:  el  soporte  para  browscap  fue  anadido  en  la  version  3.0b2  de  PHP. 


ignore_user_abort  <php  3>=  3.0.7,  PHP  4  >=  4.0.0 

Establece  si  la  desconexion  de  un  cliente  debe  suspender  la  ejecucion  del  script 

int  ignore_user_abort  (  [int  setting] ) 
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Esta  funcion  establece  si  la  desconexion  de  un  cliente  debe  provocar  la  suspension  del  script.  Devolvera 
el  valor  previo  y  puede  ser  llamada  sin  argumentos  para  devolver  el  valor  actual  y  no  cambiarlo.  Vease  la 
seccion  sobre  la  Gestion  de  la  Conexion  en  el  capltulo  Caracterfsticas  para  una  description  completa  de 
la  gestion  de  la  conexion  en  PHP. 


iptcparse  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 


Divide  un  bloque  binario  IPTC  http://www.xe.net/iptc/  (http://www.xe.net/iptc/)  en  su  tags  (etiquetas) 
individuales. 


array  iptcparse  (string  iptcblock) 


Esta  funcion  divide  un  bloque  binario  IPTC  en  sus  tags  individuales.  Devuelve  un  array  utilizando  el 
tagmarker  (marcador  de  etiqueta)  como  un  Indice  y  el  valor  como  valor.  Devuelve  false  en  caso  de 
error  o  si  no  hubiese  datos  IPTC.  Vease  GetlmageSizeO  para  un  ejemplo. 


leak  (PHP  3,  PHP  4  >=4.0.0) 

Filtra  memoria 

void  leak  (int  bytes) 

Ieak()  filtra  la  cantidad  de  memoria  especificada. 

Es  muy  util  cuando  se  depura  el  gestor  de  memoria,  que  automaticamente  libera  la  memoria  "filtrada" 
despues  de  que  se  completa  cada  peticion. 


pack  (PHP  3,  PHP  4  >=  4.0.0) 

empaqueta  datos  en  una  cadena  binaria 

string  pack  (string  format  [,  mixed  args...]) 


Empaqueta  los  argumentos  dados  en  una  cadena  binaria  siguiendo  el  formato  format.  Devuelve  la 
cadena  binaria  que  contiene  los  datos. 
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El  concepto  de  esta  funcion  fue  tornado  de  Perl  y  todos  los  codigos  de  formateo  realizan  la  misma 
funcion.  La  cadena  de  formato  consiste  en  codigos  de  formato  seguidos  por  un  argumento  opcional  de 
repeticion.  El  argumento  de  repeticion  puede  ser  un  valor  entero  o  *  para  repetir  hasta  el  fin  de  la  entrada 
de  datos.  Para  a.  A,  h,  H  la  cuenta  de  repeticion  representa  cuantos  caracteres  se  toman  de  un  argumento 
de  datos,  para  @  es  la  posicion  absoluta  donde  poner  los  datos  siguientes,  para  todo  lo  demas  la  cuenta 
de  repeticion  especifica  cuantos  argumentos  de  datos  se  toman  y  empaquetan  en  la  cadena  binaria 
resultante.  Actualmente  estan  implementados: 

•  a  cadena  rellena  de  NUL 

•  A  cadena  rellena  de  ESPACIOS 

•  h  cadena  Hex,  primero  el  medio  byte  inferior 

•  H  cadena  Hex,  primero  el  medio  byte  superior 

•  c  signed  (con  signo)  char 

•  C  unsigned  (sin  signo)  char 

•  s  signed  short  (siempre  16  bits,  distribucion  de  bytes  de  la  maquina) 

•  S  unsigned  short  (siempre  16  bits,  distribucion  de  bytes  de  la  maquina) 

•  n  unsigned  short  (siempre  16  bits,  distribucion  de  bytes  gran  endian) 

•  v  unsigned  short  (siempre  16  bits,  distribucion  de  bytes  pequeno  endian) 

•  i  signed  integer  (distribucion  de  bytes  y  tamanos  dependientes  de  la  maquina) 

•  I  unsigned  integer  (distribucion  de  bytes  y  tamanos  dependientes  de  la  maquina) 

•  1  signed  long  (siempre  32  bits,  distribucion  de  bytes  de  la  maquina) 

•  L  unsigned  long  (siempre  32  bits,  distribucion  de  bytes  de  la  maquina) 

•  N  unsigned  long  (siempre  32  bits,  distribucion  de  bytes  gran  endian) 

•  V  unsigned  long  (siempre  32  bits,  distribucion  de  bytes  pequeno  endian) 

•  f  float  (representacion  y  tamano  dependientes  de  la  maquina) 

•  d  double  (representacion  y  tamano  dependientes  de  la  maquina) 

•  x  byte  NUL 

•  X  Un  byte  hacia  atras 

•  @  relleno  con  NUL  en  la  posicion  absoluta 

Ejemplo  1.  cadena  de  formato  para  pack 

$binarydata  =  pack("nvc*",  0x1234,  0x5678,  65,  66); 

La  cadena  binaria  resultante  tendra  6  bytes  de  longitud  y  contendra  la  secuencia  de  bytes  0x12,  0x34, 
0x78,  0x56,  0x41,  0x42. 
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Adviertase  que  la  distincion  entre  valores  signed  (con  signo)  y  unsigned  (sin  signo)  solo  afecta  a  la 
funcion  unpack'),  ya  que  la  funcion  pack()  da  el  mismo  resultado  para  codigos  de  formato  con  signo  y 
sin  signo. 

Notese  tambien  que  internamente  PHP  almacena  valores  enteros  como  valores  con  signo  de  un  tamano 
dependiente  de  la  maquina.  Si  le  da  un  valor  entero  sin  signo  demasiado  grande  para  ser  almacenado, 
sera  convertido  a  un  double  (doble),  lo  que  a  menudo  produce  resultados  no  deseados. 


serialize  (PHP  3>=  3.0.5,  PHP  4  >=  4.0.0) 

genera  una  representacion  almacenable  de  un  valor 

string  serialize  (mixed  value) 


serialized  devuelve  una  cadena  que  contiene  una  representacion  byte-stream  de  value  (valor)  que 
puede  ser  almacenada  en  algun  lugar. 

Esto  es  util  para  almacenar  o  pasar  valores  PHP  sin  perdida  de  su  tipo  y  estructura. 

Para  convertir  de  nuevo  la  cadena  serializada  en  un  valor  PHP,  utilice  unserialize ').  serialized  gestiona 
los  tipos  integer,  double,  string,  array  (multidimensional)  y  object  (las  propiedades  del  objeto  pueden  ser 
serializadas,  pero  se  pierden  los  metodos). 


Ejemplo  1.  ejemplo  serialize 

//  $session_data  contains  a  multi-dimensional  array  with  session 
//  information  for  the  current  user.  We  use  serialize  ()  to  store 
//  it  in  a  database  at  the  end  of  the  request . 

$conn  =  odbc_connect ( "webdb" ,  "php",  "chicken"); 

$stmt  =  odbc_prepare ( $conn, 

"UPDATE  sessions  SET  data  =  ?  WHERE  id  =  ?"); 
$sqldata  =  array (serialize ($session_data)  ,  $PHP_AUTH_USER) ; 
if  ( ! odbc_execute ($stmt,  &$sqldata) )  { 

$stmt  =  odbc_prepare ( $conn, 

"INSERT  INTO  sessions  (id,  data)  VALUES (?,  ?)"); 
if  ( ! odbc_execute ($stmt,  &$sqldata) )  { 

/*  Something  went  wrong.  Bitch,  whine  and  moan.  */ 

} 

} 
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sleep  (PHP  3,  PHP  4  >=  4.0.0) 

Ejecucion  retardada 

void  sleep  (int  seconds) 

La  funcion  sleep  retarda  la  ejecucion  del  programa  durante  el  numero  de  seconds  (segundos)  dado. 
Vease  tambien  usleepf). 


uniqid 


(PHP  3,  PHP  4  >=  4.0.0) 


Genera  un  id  unico. 


int  uniqid  (string  prefix  [,  boolean  leg]) 


uniqid()  devuelve  un  identificador  unico  con  un  prefijo  basado  en  la  hora  actual  en  microsegundos.  El 
prefijo  puede  ser  practico  por  ejemplo  si  se  generan  identificadores  simultaneamente  en  varios  host  que 
pueden  haber  generado  el  identificador  en  el  mismo  microsegundo.  prefix  (prefijo)  puede  ser  de  hasta 
114  caracteres  de  longitud. 

Si  el  parametro  opcional  1  eg  es  true,  uniqid()  anadira  entropia  "LCG  combinada"  al  final  del  valor 
devuelto,  que  hara  el  resultado  mas  unico. 

Con  un  prefix  (prefijo)  vaefo,  la  cadena  devuelta  tendra  una  longitud  de  13  caracteres.  Si  leg  es 
true,  tendra  23  caracteres. 

Nota:  El  parametro  leg  esta  disponible  solo  en  PHP  4  y  PHP  3.0.13  y  posteriores. 


Si  necesita  un  identificador  unico  o  testigo,  y  tiene  la  intencion  de  hacer  publico  ese  testigo  al  usuario 
por  medio  de  una  red  (i.e.  cookies  de  sesion)  se  recomienda  que  utilice  algo  parecido  a  estas  lfneas 


$token  =  md5 (uniqid ("")) ;  //  no  random  portion 

$better_token  =  md5 (uniqid (rand ())) ;  //  better,  difficult  to  guess 


Esto  creara  un  identificador  de  32  caracteres  (un  numero  hexadecimal  de  128  bits)  que  es 
extremadamente  diffcil  de  predecir. 
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desempaqueta  datos  de  una  cadena  binaria 

array  unpack  (string  format,  string  data) 


Desempaqueta  datos  de  una  cadena  binaria  en  un  array,  de  acuerdo  al  formato  format.  Devuelve  un 
array  que  contiene  los  elementos  de  la  cadena  binaria  desempaquetados. 

Unpack  funciona  de  manera  ligeramente  diferente  a  Perl,  ya  que  los  datos  desempaquetados  se 
almacenan  en  un  array  asociativo.  Para  conseguir  esto  debe  nombrar  los  diferentes  codigos  de  formato  y 
separarlos  por  una  barra  inclinada  /. 

Ejemplo  1.  cadena  de  formato  unpack 

$array  =  unpack (" c2chars/nint " ,  $binarydata) ; 

El  array  resultante  contendra  las  entradas  "charsl",  "chars2"  y  "int". 


Para  una  explication  de  los  codigos  de  formato  vease  tambien:  packQ 

Advierta  que  PHP  almacena  internamente  los  valores  enteros  con  signo.  Si  desempaqueta  un  unsigned 
long  (largo  sin  signo)  demasiado  grande  y  es  del  mismo  tamano  tal  como  PHP  almacena  internamente 
los  valores,  el  resultado  sera  un  numero  negativo  a  pesar  de  que  se  especificara  desempaquetamiento  sin 
signo. 


unserialize  (PHP  3>=  3.0.5,  PHP  4  >=  4.0.0) 


crea  un  valor  PHP  de  una  representation  almacenada 


mixed  unserialize  (string  str) 


unserialize()  toma  una  variable  serializada  (vease  serialize^))  y  la  convierte  en  un  valor  PHP.  Se 
devuelve  el  valor  convertido,  y  puede  ser  un  integer  (entero),  double  (doble),  string  (cadena),  array  o 
object  (objeto).  Si  fue  serializado  un  objeto,  sus  metodos  no  son  conservados  en  el  valor  devuelto. 


Ejemplo  1.  ejemplo  unserialize 

//  Here,  we  use  unserialize ( )  to  load  session  data  from  a  database 
//  into  $session_data .  This  example  complements  the  one  described 
//  with  serializeO  . 
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$conn  =  odbc_connect ( "webdb" ,  "php",  "chicken"); 

$stmt  =  odbc  prepare ($conn,  "SELECT  data  FROM  sessions  WHERE  id  =  ?"); 
$sqldata  =  array ( $PHP_AUTH_USER) ; 

if  ( ! odbc_execute ($stmt,  &$sqldata)  | I  ! odbc_f etch_into ( $stmt ,  &$tmp) )  { 

//  if  the  execute  or  fetch  fails,  initialize  to  empty  array 
$session_data  =  array  (); 

}  else  { 

//  we  should  now  have  the  serialized  data  in  $tmp[0] . 

$session_data  =  unserialize ( $tmp [ 0 ]) ; 
if  ( ! is_array ($session_data) )  { 

//  something  went  wrong,  initialize  to  empty  array 
$session_data  =  array!) ; 

} 

} 


usleep  (PHP  3,  PHP  4  >=  4.0.0) 


Retrasa  la  ejecucion,  en  microsegundos 


void  usleep  (int  micro_seconds) 


La  funcion  usleep  retrasa  la  ejecucion  del  programa  durante  un  numero  de  micro_seconds 
(microsegundos)  dado. 

Vease  tambien  sleep)). 
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LIN.  mnoGoSearch  Functions 


These  functions  allow  you  to  access  mnoGoSearch  (former  UdmSearch)  free  search  engine.  In  order  to 
have  these  functions  available,  you  must  compile  php  with  mnogosearch  support  by  using  the 
— with-mnogosearch  option.  If  you  use  this  option  without  specifying  the  path  to  mnogosearch,  php 
will  look  for  mnogosearch  under  /usr/local/mnogosearch  path  by  default.  If  you  installed  mnogosearch  at 
other  path  you  should  specify  it:  — with-mnogosearch=DlR. 

mnoGoSearch  is  a  full-featured  search  engine  software  for  intranet  and  internet  servers,  distributed  under 
the  GNU  license.  mnoGoSearch  has  number  of  unique  features,  which  makes  it  appropriate  for  a  wide 
range  of  application  from  search  within  your  site  to  a  specialized  search  system  such  as  cooking  recipes 
or  newspaper  search,  ftp  archive  search,  news  articles  search,  etc.  It  offers  full-text  indexing  and 
searching  for  HTML,  PDF,  and  text  documents.  mnoGoSearch  consists  of  two  parts.  The  first  is  an 
indexing  mechanism  (indexer).  The  purpose  of  indexer  is  to  walk  through  HTTP,  FTP,  NEWS  servers  or 
local  files,  recursively  grabbing  all  the  documents  and  storing  meta-data  about  that  documents  in  a  SQL 
database  in  a  smart  and  effective  manner.  After  every  document  is  referenced  by  its  corresponding  URL, 
meta-data  collected  by  indexer  is  used  later  in  a  search  process.  The  search  is  performed  via  Web 
interface.  C  CGI,  PHP  and  Perl  search  front  ends  are  included. 

Nota:  php  contains  built-in  mysql  access  library,  which  can  be  used  to  access  mysql.  It  is  known  that 
mnoGoSearch  is  not  compatible  with  this  built-in  library  and  can  work  only  with  generic  mysql 
libraries.  Thus,  if  you  use  mnoGoSearch  with  mysql,  during  php  configuration  you  have  to  indicate 
directory  of  mysql  installation,  that  was  used  during  mnoGoSearch  configuration,  i.e.  for  example: 

— with-mnogosearch  — with-mysql=/ usr. 


You  need  at  least  3.1.10  version  of  mnoGoSearch  installed  to  use  these  functions. 
More  information  about  mnoGoSearch  can  be  found  at  http://www.mnogosearch.ru/. 
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udm_add_search  limit  (php 4 >=  4.0.5) 


Add  various  search  limits 


int  udm_add_search_limit  (int  agent,  int  var,  string  val) 


udm_add_search_limit()  returns  true  on  success,  false  on  error.  Adds  search  restrictions. 

agent  -  a  link  to  Agent,  received  after  call  to  udm_alloc_agentO. 

var  -  defines  parameter,  indicating  limit. 

val  -  defines  value  of  the  current  parameter. 

Possible  var  values: 

•  UDM_LIMIT_URL  -  defines  document  URL  limitations  to  limit  search  through  subsection  of 
database.  It  supports  SQL  %  and  _  LIKE  wildcards,  where  %  matches  any  number  of  characters,  even 

zero  characters,  and  _  matches  exactly  one  character.  E.g.  http://my.domain. _ /catalog  may  stand  for 

http://my.domain.ru/catalog  and  http://my.domain.ua/catalog. 

•  UDM_LIMIT_TAG  -  defines  site  TAG  limitations.  In  indexer-conf  you  can  assign  specific  TAGs  to 
various  sites  and  parts  of  a  site.  Tags  in  mnoGoSearch  3.1.x  are  lines,  that  may  contain  metasymbols 
%  and  _.  Metasymbols  allow  searching  among  groups  of  tags.  E.g.  there  are  links  with  tags  ABCD 
and  ABCE,  and  search  restriction  is  by  ABC_  -  the  search  will  be  made  among  both  of  the  tags. 

•  UDMJLIMITJLANG  -  defines  document  language  limitations. 

•  UDM_LIMIT_CAT  -  defines  document  category  limitations.  Categories  are  similar  to  tag  feature,  but 
nested.  So  you  can  have  one  category  inside  another  and  so  on.  You  have  to  use  two  characters  for 
each  level.  Use  a  hex  number  going  from  0-F  or  a  36  base  number  going  from  0-Z.  Therefore  a 
top-level  category  like  ’Auto’  would  be  01.  If  it  has  a  subcategory  like  ’Ford’,  then  it  would  be  01  (the 
parent  category)  and  then  ’Ford’  which  we  will  give  01.  Put  those  together  and  you  get  0101.  If  ’Auto’ 
had  another  subcategory  named  ’  VW’,  then  it’s  id  would  be  01  because  it  belongs  to  the  ’Ford’ 
category  and  then  02  because  it’s  the  next  category.  So  it’s  id  would  be  0102.  If  VW  had  a  sub 
category  called  ’Engine’  then  it’s  id  would  start  at  01  again  and  it  would  get  the  ’  VW’  id  02  and 
’Auto’  id  of  01,  making  it  010201.  If  you  want  to  search  for  sites  under  that  category  then  you  pass  it 
cat=0 10201  in  the  url. 

•  UDM_LIMIT_DATE  -  defines  limitation  by  date  document  was  modified. 

Format  of  parameter  value:  a  string  with  first  character  <  or  >,  then  with  no  space  -  date  in  unixtime 
format,  for  example: 

Udm_Add_Search_Limit($udm,UDM_LIMIT_DATE,"<908012006"); 

If  >  character  is  used,  then  search  will  be  restricted  to  those  documents  having  modification  date 
greater  than  entered.  If  <,  then  smaller. 
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udm_alloc_agent  (php  4  >=  4.0.5) 


Allocate  mnoGoSearch  session 


int  udm_alloc_agent  (string  dbaddr  [,  strinqdbmode] ) 


udm_alloc_agent()  returns  mnogosearch  agent  identifier  on  success,  false  on  error.  This  function 
creates  a  session  with  database  parameters. 

dbaddr  -  URL-style  database  description.  Options  (type,  host,  database  name,  port,  user  and  password) 
to  connect  to  SQL  database.  Do  not  matter  for  built-in  text  files  support.  Format:  DBAddr 
DBType:[//[DBUser[:DBPass]@]DBHost[:DBPort]]/DBName/  Currently  supported  DBType  values  are: 
mysql,  pgsql,  msql,  solid,  mssql,  oracle,  ibase.  Actually,  it  does  not  matter  for  native  libraries  support. 
But  ODBC  users  should  specify  one  of  supported  values.  If  your  database  type  is  not  supported,  you  may 
use  "unknown"  instead. 

dbmode  -  You  may  select  SQL  database  mode  of  words  storage.  When  "single"  is  specified,  all  words 
are  stored  in  the  same  table.  If  "multi"  is  selected,  words  will  be  located  in  different  tables  depending  of 
their  lengths,  "multi"  mode  is  usually  faster  but  requires  more  tables  in  database.  If  "crc"  mode  is 
selected,  mnoGoSearch  will  store  32  bit  integer  word  IDs  calculated  by  CRC32  algorythm  instead  of 
words.  This  mode  requres  less  disk  space  and  it  is  faster  comparing  with  "single"  and  "multi"  modes, 
"crc-multi"  uses  the  same  storage  structure  with  the  "crc"  mode,  but  also  stores  words  in  different  tables 
depending  on  words  lengths  like  "multi"  mode.  Format:  DBMode  single/multi/crc/crc -multi 

Nota:  dbaddr  and  dbmode  must  match  those  used  during  indexing. 


Nota:  In  fact  this  function  does  not  open  connection  to  database  and  thus  does  not  check  entered 
login  and  password.  Actual  connection  to  database  and  login/password  verification  is  done  by 
udm_find[). 


udm_api_version  (php  4  >=  4 .0 ,5) 

Get  mnoGoSearch  API  version. 

int  udm_api_version  () 


udm_api_version()  returns  mnoGoSearch  API  version  number.  E.g.  if  mnoGoSearch  3.1.10  API  is 
used,  this  function  will  return  30110. 
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This  function  allows  user  to  identify  which  API  functions  are  available,  e.g.  udm_get_doc_count') 
function  is  only  available  in  mnoGoSearch  3.1.11  or  later. 

Example: 

if  (Udm_Api_Version ( )  >=  30111)  { 

print  "Total  number  of  urls  in  database:  " . Udm_Get_Doc_Count ( $udm) . "<br>\n" 
} 


udm_cat_path  (php  4  >=  4.0.6) 


Get  the  path  to  the  current  category. 


array  udm_cat_path  (int  agent, 


string  category) 


udm_cat_path()  returns  array  describing  path  in  the  categories  tree  from  the  tree  root  to  the  current 
category. 

agent  -  agent  link  identifier. 

category  -  current  category  -  the  one  to  get  path  to. 

Returns  array  with  the  following  format: 

The  array  consists  of  pairs.  Elements  with  even  index  numbers  contain  category  paths,  odd  elements 
contain  corresponding  category  names. 

For  example,  the  call  $array=udm_cat_path  ($agent,  '  02031D'  )  ;  may  return  the  following  array: 

$array[0]  will  contain  ” 

$array[l]  will  contain  ’Root’ 

$array[2]  will  contain  ’02’ 

$array[3]  will  contain  ’Sport’ 

$array[4]  will  contain  ’0203’ 

$array[5]  will  contain  ’Auto’ 

$array[4]  will  contain  ’0203 ID’ 

$array[5]  will  contain  ’Ferrari’ 


Ejemplo  1.  Specifying  path  to  the  current  category  in  the  following  format:  ’>  Root  >  Sport  >  Auto 
>  Ferrari’ 

<?php 

$cat_path_arr=Udm_Cat_Path ($udm_agent, $cat) ; 

$cat_path=" ; 

for  ($i=0;  $i<count ( $cat_path_arr ) ;  $i+=2)  { 

$path=$cat_path_arr [ $i ] ; 
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$name=$cat_path_arr [ $i  +  l  ]  ; 

$cat_path  .=  "  >  <a  href =\ " $PHP_SELF?cat=$path\ ">$name</a> 


> 


udmcat  list  (php  4  >=  4.0.6) 

Get  all  the  categories  on  the  same  level  with  the  current  one. 

array  udm_cat_list  (int  agent,  string  category) 


udm_cat_list()  returns  array  listing  all  categories  of  the  same  level  as  current  category  in  the  categories 
tree. 

The  function  can  be  useful  for  developing  categories  tree  browser. 

Returns  array  with  the  following  format: 

The  array  consists  of  pairs.  Elements  with  even  index  numbers  contain  category  paths,  odd  elements 
contain  corresponding  category  names. 

$array[0]  will  contain  ’020300’ 

$array[l]  will  contain  ’Audo’ 

$array[2]  will  contain  ’020301’ 

$array[3]  will  contain  ’BMW’ 

$array[4]  will  contain  ’020302’ 

$array[5]  will  contain  ’Opel’ 

etc. 


Following  is  an  example  of  displaying  links  of  the  current  level  in  format: 
Audi 
BMW 
Opel 


<?php 

$cat_list_arr=Udm_Cat_List ($udm_agent,  $cat) ; 

$cat_list=" ; 

for  ($i=0;  $i<count ($cat_list_arr) ;  $i+=2)  { 

$path=$cat_list_arr [ $ i ] ; 

$name=$cat_list_arr [ $i+l ] ; 

$cat_list  .=  "<a  href =\ " $PHP_SELF?cat=$path\ ">$name</a><br> " ; 
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udm  clear  search  limits  (php 4 >=  4.0.5) 

Clear  all  mnoGoSearch  search  restrictions 

int  udm_clear_search_limits  (int  agent) 

udm_clear_search_limits()  resets  defined  search  limitations  and  returns  true. 

udm_errnO(PHP4>=4  0  5) 

Get  mnoGoSearch  error  number 

int  udm_errno  (int  agent) 

udm_errno()  returns  mnoGoSearch  error  number,  zero  if  no  error. 
agent  -  link  to  agent  identifier,  received  after  call  to  udm_alloc_agent'). 
Receiving  numeric  agent  error  code. 

udm_error(PHP4>=4  0  5) 

Get  mnoGoSearch  error  message 

string  udm_error  (int  agent) 

udm_error()  returns  mnoGoSearch  error  message,  empty  string  if  no  error. 
agent  -  link  to  agent  identifier,  received  after  call  to  udm_alloc_agentO- 
Receiving  agent  error  message. 
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udmfind  (php4>=4o5) 


Perform  search 


int  udm_find  (int  agent,  string  query) 


udm_find()  returns  result  link  identifier  on  success,  false  on  error. 

The  search  itself.  The  first  argument  -  session,  the  next  one  -  query  itself.  To  find  something  just  type 
words  you  want  to  find  and  press  SUBMIT  button.  For  example,  "mysql  odbc".  You  should  not  use 
quotes  "  in  query,  they  are  written  here  only  to  divide  a  query  from  other  text.  mnoGoSearch  will  find  all 
documents  that  contain  word  "mysql"  and/or  word  "odbc".  Best  documents  having  bigger  weights  will 
be  displayed  first.  If  you  use  search  mode  ALL,  search  will  return  documents  that  contain  both  (or  more) 
words  you  entered.  In  case  you  use  mode  ANY,  the  search  will  return  list  of  documents  that  contain  any 
of  the  words  you  entered.  If  you  want  more  advanced  results  you  may  use  query  language.  You  should 
select  "bool"  match  mode  in  the  search  from. 

mnoGoSearch  understands  the  following  boolean  operators: 

&  -  logical  AND.  For  example,  "mysql  &  odbc".  mnoGoSearch  will  find  any  URLs  that  contain  both 
"mysql"  and  "odbc". 

I  -  logical  OR.  For  example  "mysqllodbc".  mnoGoSearch  will  find  any  URLs,  that  contain  word  "mysql" 
or  word  "odbc". 

~  -  logical  NOT.  For  example  "mysql  &  -odbc".  mnoGoSearch  will  find  URLs  that  contain  word 
"mysql"  and  do  not  contain  word  "odbc"  at  the  same  time.  Note  that  -  just  excludes  given  word  from 
results.  Query  "-odbc"  will  find  nothing! 

()  -  group  command  to  compose  more  complex  queries.  For  example  "(mysql  I  msql)  &  -postgres". 
Query  language  is  simple  and  powerful  at  the  same  time.  Just  consider  query  as  usual  boolean  expression. 


udmf  ree_agent  (php  4  >=  4.o.5) 

Free  mnoGoSearch  session 

int  udm_f ree_agent  (int  agent) 

udm_free_agent()  returns  true  on  success,  false  on  error. 

agent  -  link  to  agent  identifier,  received  ‘  after  call  to  udm_alloc_agent'). 

Freeing  up  memory  allocated  for  agent  session. 
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udmf  ree  Jspell_data  (php  4  >=  4.0.5) 

Free  memory  allocated  for  ispell  data 

int  udm_f ree_ispell_data  (int  agent ) 

udm_free_ispell_data()  always  returns  true. 

agent  -  agent  link  identifier,  received  after  call  to  udm_alloc_agent'). 

Nota:  This  function  is  supported  beginning  from  version  3.1.12  of  mnoGoSearch  and  it  does  not  do 
anything  in  previous  versions. 


udmf  ree_res  (php  4  >=  4.0.5) 

Free  mnoGoSearch  result 

int  udm_f ree_res  (int  res) 

udm_free_res()  returns  true  on  success,  false  on  error. 
res  -  a  link  to  result  identifier,  received  after  call  to  udm_find). 

Freeing  up  memory  allocated  for  results. 

udm_get_doc_count  <php  4  >=  4  o  5) 

Get  total  number  of  documents  in  database. 

int  udm_get_doc_count  (int  agent ) 

udm_get_doc_count()  returns  nuimber  of  documents  in  database. 
agent  -  link  to  agent  identifier,  received  after  call  to  udm_alloc_agentO- 

Nota:  This  function  is  supported  only  in  mnoGoSearch  3.1 .1 1  or  later. 
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udm_get_res_f  ield  (php  4  >=  4.0.5) 

Fetch  mnoGoSearch  result  field 

string  udm_get_res_f ield  (int  res,  int  row,  int  field) 

udm_get_res_field()  returns  result  field  value  on  success,  false  on  error. 
res  -  a  link  to  result  identifier,  received  after  call  to  udm_find). 

row  -  the  number  of  the  link  on  the  current  page.  May  have  values  from  0  to  UDM_PARAM_NUM_ROWS . 
field  -  field  identifier,  may  have  the  following  values: 

•  UDM_FIELD_URL  -  document  URL  field 

•  UDM_FIELD_CONTENT  -  document  Content-type  field  (for  example,  text/html). 

•  UDM_FIELD_CATEGORY  -  document  category  field.  Use  udm_cat_path ')  to  get  full  path  to  current 
category  from  the  categories  tree  root.  (This  parameter  is  available  only  in  PHP  4.0.6  or  later). 

•  UDM_FIELD_TITLE  -  document  title  field. 

•  1  IDM  ETEl  .DKEYWORDS  -  document  keywords  field  (from  META  KEYWORDS  tag). 

•  UDM_FIELD_DESC  -  document  description  field  (from  META  DESCRIPTION  tag). 

•  UDM_FIELD_TEXT  -  document  body  text  (the  first  couple  of  lines  to  give  an  idea  of  what  the 
document  is  about). 

•  UDM_FIELD_SIZE  -  document  size. 

•  UDM_FIELD_URLID  -  unique  URL  ID  of  the  link. 

•  UDM_FIELD_RATING  -  page  rating  (as  calculated  by  mnoGoSearch). 

•  UDM_FIELD_MODIFIED  -  last-modified  field  in  unixtime  format. 

•  UDM_FIELD_ORDER  -  the  number  of  the  current  document  in  set  of  found  documents. 

•  UDM_FIELD_CRC  -  document  CRC. 


udm_get_res_param  (php  4  >=  4.o.5) 

Get  mnoGoSearch  result  parameters 

string  udm  get  res  param  (int  res,  int  param) 

udm_get_res_param()  returns  result  parameter  value  on  success,  false  on  error. 
res  -  a  link  to  result  identifier,  received  after  call  to  udm_find  ). 
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param  -  parameter  identifier,  may  have  the  following  values: 

•  UDM_PARAM_NUM_ROWS  -  number  of  received  found  links  on  the  current  page.  It  is  equal  to 
UDM_PARAM_PAGE_SIZE  for  all  search  pages,  on  the  last  page  -  the  rest  of  links. 

•  UDM_PARAM_FOUND  -  total  number  of  results  matching  the  query. 

•  UDM_PARAM_WORDINFO  -  information  on  the  words  found.  E.g.  search  for  "a  good  book"  will 
return  "a:  stopword,  good:5637,  book:  120" 

•  UDM_PARAM_SEARCHTIME  -  search  time  in  seconds. 

•  UDM_PARAM_FIRST_DOC  -  the  number  of  the  first  document  displayed  on  current  page. 

•  UDM_PARAM_LAST_DOC  -  the  number  of  the  last  document  displayed  on  current  page. 


udm  _load_ispell_data  (php  4  >=  4.0.5) 


Load  ispell  data 


int  udm_load_ispell_data  (int  agent,  int  var,  string  vail,  string  val2,  int 
flag) 


udm_load_ispell_data()  loads  ispell  data.  Returns  true  on  success,  false  on  error. 

agent  -  agent  link  identifier,  received  after  call  to  ud  m_a  1 1  oc_agen  t ') . 

var  -  parameter,  indicating  the  source  for  ispell  data.  May  have  the  following  values: 

After  using  this  function  to  free  memory  allocated  for  ispell  data,  please  use  udm_free_ispell_dataO, 
even  if  you  use  UDM_ISPELL_TYPE_SERVER  mode. 

The  fastest  mode  is  UDM_ISPELL_TYPE_SERVER.  UDM_ISPELL_TYPE_TEXT  is  slower  and 
UDM_ISPELL_TYPE_DB  is  the  slowest.  The  above  pattern  is  true  for  mnoGoSearch  3. 1.10-3. 1.11. 
It  is  planned  to  speed  up  DB  mode  in  future  versions  and  it  is  going  to  be  faster  than  TEXT  mode. 


•  UDM_ISPELL_TYPE_DB  -  indicates  that  ispell  data  should  be  loaded  from  SQL.  In  this  case, 
parameters  vail  and  val2  are  ignored  and  should  be  left  blank,  flag  should  be  equal  to  1. 

Nota:  flag  indicates  that  after  loading  ispell  data  from  defined  source  it  sould  be  sorted  (it  is 
necessary  for  correct  functioning  of  ispell).  In  case  of  loading  ispell  data  from  files  there  may  be 
several  calls  to  udmJoad_ispell_data(),  and  there  is  no  sense  to  sort  data  after  every  call,  but 
only  after  the  last  one.  Since  in  db  mode  all  the  data  is  loaded  by  one  call,  this  parameter  should 
have  the  value  i.  In  this  mode  in  case  of  error,  e.g.  if  ispell  tables  are  absent,  the  function  will 
return  false  and  code  and  error  message  will  be  accessible  through  udm_error;)  and 
udm_errno[). 


Example: 
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if  ( !  Udm_Load_I spell_Data ( $udm, UDM_ISPELL_TYPE_DB, ",  ",  1 ) )  { 

printf ( "Error  #%d:  '  %s' \n"  ,  Udm_Errno ( $udm) , Udm_Error ( $udm) ) ; 

exit ; 

} 


•  UDM_ISPELL_TYPE_AFFIX  -  indicates  that  ispell  data  should  be  loaded  from  file  and  initiates 
loading  affixes  file.  In  this  case  vail  defines  double  letter  language  code  for  which  affixes  are  loaded, 
and  val2  -  file  path.  Please  note,  that  if  a  relative  path  entered,  the  module  looks  for  the  file  not  in 
UDM_CONF_DIR,  but  in  relation  to  current  path,  i.e.  to  the  path  where  the  script  is  executed.  In  case 
of  error  in  this  mode,  e.g.  if  file  is  absent,  the  function  will  return  false,  and  an  error  message  will  be 
displayed.  Error  message  text  cannot  be  accessed  through  udm_error')  and  udm_errno'),  since  those 
functions  can  only  return  messages  associated  with  SQL.  Please,  see  flag  parameter  description  in 
UDM_ISPELL_TYPE_DB . 

Example: 


if  ( ( !  Udm_Load_Ispell_Data ( $udm, UDM_ISPELL_TYPE_AFFIX, ' en' , ' / opt/ ispell/en . af f ' , 0 ) ) 

( !  Udm_Load_Ispell_Data ( $udm, UDM_ISPELL_TYPE_AFFIX, ' ru'  ,  '  / opt/ ispell/ ru . af f '  ,  0 ) )  I 
( !  Udm_Load_Ispell_Data ( $udm, UDM_ISPELL_TYPE_SPELL, ' en' , ' /opt/ ispell/en . diet ' , 0 ) ) 

( !  Udm_Load_Ispell_Data ( $udm, UDM_ISPELL_TYPE_SPELL, ' ru' , ' /opt/ ispell/ ru . diet '  ,  1 ) ) ) 


exit ; 
} 


Nota:  flag  is  equal  to  l  only  in  the  last  call. 


•  UDM_ISPELL_TYPE_SPELL  -  indicates  that  ispell  data  should  be  loaded  from  file  and  initiates 
loading  of  ispell  dictionary  file.  In  this  case  vail  defines  double  letter  language  code  for  which 
affixes  are  loaded,  and  va!2  -  hie  path.  Please  note,  that  if  a  relative  path  entered,  the  module  looks 
for  the  hie  not  in  UDM_CONF_DIR,  but  in  relation  to  current  path,  i.e.  to  the  path  where  the  script  is 
executed.  In  case  of  error  in  this  mode,  e.g.  if  hie  is  absent,  the  function  will  return  false,  and  an 
error  message  will  be  displayed.  Error  message  text  cannot  be  accessed  through  udm_error')  and 
udm_errno'),  since  those  functions  can  only  return  messages  associated  with  SQL.  Please,  see  flag 
parameter  description  in  UDM_ISPELL_TYPE_DB. 

if  ( ( !  Udm_Load_Ispell_Data ( $udm, UDM_ISPELL_TYPE_AFFIX,  '  en'  ,  ' / opt /ispell/ en . af f '  ,  0 ) ) 

( !  Udm_Load_Ispell_Data ( $udm, UDM_1SPELL_TYPE_AFF1X, ' ru' , ' / opt/ ispell/ ru . af f ' , 0 ) )  I 
( !  Udm_Load_Ispell_Data ( $udm, UDM_1SPELL_TYPE_SPELL, ' en' , ' / opt/ ispell/ en . diet ' , 0 ) ) 

( !  Udm_Load_Ispell_Data ( $udm, UDM_1SPELL_TYPE_SPELL, ' ru'  ,  ' /opt/ i spell /ru . diet '  ,  1 ) ) ) 
exit ; 

} 


Nota:  flag  is  equal  to  l  only  in  the  last  call. 
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•  UDM_ISPELL_TYPE_SERVER  -  enables  spell  server  support.  vd.1 1  parameter  indicates  address  of 
the  host  running  spell  server.  val2  ‘  is  not  used  yet,  but  in  future  releases  it  is  going  to  indicate 
number  of  port  used  by  spell  server,  flag  parameter  in  this  case  is  not  needed  since  ispell  data  is 
stored  on  spellserver  already  sorted. 

Spelld  server  reads  spell-data  from  a  separate  configuration  file 

(/usr/local/mnogosearch/etc/spelld.conf  by  default),  sorts  it  and  stores  in  memory.  With  clients  server 
communicates  in  two  ways:  to  indexer  all  the  data  is  transferred  (so  that  indexer  starts  faster),  from 
search. cgi  server  receives  word  to  normalize  and  then  passes  over  to  client  (search.cgi)  list  of 
normalized  word  forms.  This  allows  fastest,  compared  to  db  and  text  modes  processing  of  search 
queries  (by  omitting  loading  and  sorting  all  the  spell  data). 

udm_load_ispell_data()  function  in  UDM_ISPELL_TYPE_SERVER  mode  does  not  actually  load 
ispell  data,  but  only  defines  server  address.  In  fact,  server  is  automatically  used  by  udm_find') 
function  when  performing  search.  In  case  of  errors,  e.g.  if  spellserver  is  not  running  or  invalid  host 
indicated,  there  are  no  messages  returned  and  ispell  conversion  does  not  work. 

Nota:  This  function  is  available  in  mnoGoSearch  3.1.12  or  later. 


Example: 

if  ( !  Udm_Load_Ispell_Data ( $udm, UDM_ISPELL_TYPE_SERVER, ",  ",  1) )  { 

printf ( "Error  loading  ispell  data  from  server<br>\n" ) ; 
exit  ; 

} 


udm_set_agent_param  php 4  >=  4.0.5) 

Set  mnoGoSearch  agent  session  parameters 

int  udm  set  agent  param  (int  agent,  int  var,  string  val ) 

udm_set_agent_param()  returns  true  on  success,  false  on  error.  Defines  mnoGoSearch  session 
parameters. 

The  following  parameters  and  their  values  are  available: 

•  UDM_PARAM_PAGE_NUM  -  used  to  choose  search  results  page  number  (results  are  returned  by 
pages  beginning  from  0,  with  UDM_PARAM_PAGE_SIZE  results  per  page). 
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UDM_PARAM_PAGE_SIZE  -  number  of  search  results  displayed  on  one  page. 

UDM_PARAM_SEARCH_MODE  -  search  mode.  The  following  values  available: 
UDM_MODE_ALL  -  search  for  all  words;  UDM_MODE_ANY  -  search  for  any  word; 
UDM_MODE_PHRASE  -  phrase  search;  UDM_MODE_BOOL  -  boolean  search.  See  udmfind')  for 
details  on  boolean  search. 

UDM_PARAM_CACHE_MODE  -  turns  on  or  off  search  result  cache  mode.  When  enabled,  the 
search  engine  will  store  search  results  to  disk.  In  case  a  similar  search  is  performed  later,  the  engine 
will  take  results  from  the  cache  for  faster  performance.  Available  values:  UDM_CACHE_ENABLED, 
UDM_CACHE_DISABLED. 

UDM_PARAM_TRACK_MODE  -  turns  on  or  off  trackquery  mode.  Since  version  3.1.2 
mnoGoSearch  has  a  query  tracking  support.  Note  that  tracking  is  implemented  in  SQL  version  only 
and  not  available  in  built-in  database.  To  use  tracking,  you  have  to  create  tables  for  tracking  support. 
For  MySQL,  use  create/mysql/track.txt.  When  doing  a  search,  front-end  uses  those  tables  to  store 
query  words,  a  number  of  found  documents  and  current  UNIX  timestamp  in  seconds.  Available 
values:  UDM_TRACK_ENABLED,  UDM_TRACK_DISABLED. 

UDM_PARAM_PHRASE_MODE  -  defines  whether  index  database  using  phrases  ("phrase" 
parameter  in  indexer. conf).  Possible  values:  UDM_PHRASE_ENABLED  and 
UDM_PHRASE_DISABLED.  Please  note,  that  if  phrase  search  is  enabled 
(UDM_PHRASE_ENABLED),  it  is  still  possible  to  do  search  in  any  mode  (ANY,  ALL,  BOOL  or 
PHRASE).  In  3.1.10  version  of  mnoGoSearch  phrase  search  is  supported  only  in  sql  and  buuilt-in 
database  modes,  while  beginning  with  3.1.11  phrases  are  supported  in  cachemode  as  well. 

Examples  of  phrase  search: 

"Arizona  desert"  -  This  query  returns  all  indexed  documents  that  contain  "Arizona  desert"  as  a  phrase. 
Notice  that  you  need  to  put  double  quotes  around  the  phrase 


UDM_PARAM_CHARSET  -  defines  local  charset.  Available  values:  set  of  charsets  supported  by 
mnoGoSearch,  e.g.  koi8-r,  cpl251,  ... 

UDM_PARAM_STOPFILE  -  Defines  name  and  path  to  stopwords  file.  (There  is  a  small  difference 
with  mnoGoSearch  -  while  in  mnoGoSearch  if  relative  path  or  no  path  entered,  it  looks  for  this  file  in 
relation  to  UDM_CONF_DIR,  the  module  looks  for  the  file  in  relation  to  current  path,  i.e.  to  the  path 
where  the  php  script  is  executed.) 

UDM_PARAM_STOPTABLE  -  Load  stop  words  from  the  given  SQL  table.  You  may  use  several 
StopwordTable  commands.  This  command  has  no  effect  when  compiled  without  SQL  database 
support. 

UDM_PARAM_WEIGHT_FACTOR  -  represents  weight  factors  for  specific  document  parts. 
Currently  body,  title,  keywords,  description,  url  are  supported.  To  activate  this  feature  please  use 
degrees  of  2  in  *Weight  commands  of  the  indexer.conf.  Let’s  imagine  that  we  have  these  weights: 

URLWeight  1 
Body  Weight  2 
TitleWeight  4 
KeywordWeight  8 
Desc  Weight  16 
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As  far  as  indexer  uses  bit  OR  operation  for  word  weights  when  some  word  presents  several  time  in  the 
same  document,  it  is  possible  at  search  time  to  detect  word  appearance  in  different  document  parts. 
Word  which  appears  only  in  the  body  will  have  00000010  argegate  weight  (in  binary  notation).  Word 
used  in  all  document  parts  will  have  0001 1111  aggregate  weight. 

This  parameter’s  value  is  a  string  of  hex  digits  ABCDE.  Each  digit  is  a  factor  for  corresponding  bit  in 
word  weight.  For  the  given  above  weights  configuration: 

E  is  a  factor  for  weight  1  (URL  Weight  bit) 

D  is  a  factor  for  weight  2  (BodyWeight  bit) 

C  is  a  factor  for  weight  4  (TitleWeight  bit) 

B  is  a  factor  for  weight  8  (KeywordWeight  bit) 

A  is  a  factor  for  weight  16  (Desc Weight  bit) 


Examples: 

UDM_PARAM_WEIGHT_FACTOR=00001  will  search  through  URLs  only. 

UDM_PAR AM_WEIGHT_FACTOR=00 1 00  will  search  through  Titles  only. 

UDM_PARAM_WEIGHT_FACTOR=l  1100  will  search  through  Title,Key words, Desctription  but  not 
through  URL  and  Body. 

UDM_PARAM_WEIGHT_FACTOR=F942 1  will  search  through: 

Description  with  factor  15  (F  hex) 

Keywords  with  factor  9 
Title  with  factor  4 
Body  with  factor  2 
URL  with  factor  1 


If  UDM_PARAM_WEIGHT_FACTOR  variable  is  ommited,  original  weight  value  is  taken  to  sort 
results.  For  a  given  above  weight  configuration  it  means  that  document  description  has  a  most  big 
weight  16. 


UDM_PARAM_WORD_MATCH  -  word  match.  You  may  use  this  parameter  to  choose  word  match 
type.  This  feature  works  only  in  "single"  and  "multi"  modes  using  SQL  based  and  built-in  database.  It 
does  not  work  in  cachemode  and  other  modes  since  they  use  word  CRC  and  do  not  support  substring 
search.  Available  values: 

UDM_MATCH_BEGIN  -  word  beginning  match; 

UDM_MATCH_END  -  word  ending  match; 

UDM_MATCH_WORD  -  whole  word  match; 

UDM_MATCH_SUBSTR  -  word  substring  match. 


UDM_PARAM_MIN_WORD_LEN  -  defines  minimal  word  length.  Any  word  shorter  this  limit  is 
considered  to  be  a  stopword.  Please  note  that  this  paraneter  value  is  inclusive,  i.e.  if 
UDM_PARAM_MIN_WORD_LEN=3,  a  word  3  characters  long  will  not  be  considered  a  stopword, 
while  a  word  2  characters  long  will  be.  Default  value  is  1. 
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UDM_PARAM_ISPELL_PRE FIXES  -  Possible  values:  UDM_PREFIXES_ENABLED  and 
UDM_PREFIXES_DISABLED,  that  respectively  enable  or  disable  using  prefixes.  E.g.  if  a  word 
"tested"  is  in  search  query,  also  words  like  "test",  "testing",  etc.  Only  suffixes  are  supported  by  default. 
Prefixes  usually  change  word  meanings,  for  example  if  somebody  is  searching  for  the  word  "tested" 
one  hardly  wants  "untested"  to  be  found.  Prefixes  support  may  also  be  found  useful  for  site’s  spelling 
checking  purposes.  In  order  to  enable  ispell,  you  have  to  load  ispell  data  with  udm_load_ispell_dataO. 

UDM_PARAM_CROSS_WORDS  -  enables  or  disables  crosswords  support.  Possible  values: 
UDM_CROSS_WORDS_ENABLED  and  UDM_CROSS_WORDS_DISABLED. 

The  corsswords  feature  allows  to  assign  words  between  <a  href="xxx">  and  </a>  also  to  a  document 
this  link  leads  to.  It  works  in  SQL  database  mode  and  is  not  supported  in  built-in  database  and 
Cachemode. 

Nota:  Crosswords  are  supported  only  in  mnoGoSearch  3.1 .1 1  or  later. 


UDM_PARAM_VARDIR  -  specifies  a  custom  path  to  directory  where  indexer  stores  data  when  using 
built-in  database  and  in  cache  mode.  By  default  /var  directory  of  mnoGoSearch  installation  is  used. 
Can  have  only  string  values.  The  parameter  is  available  in  PHP  4.1.0  or  later. 

UDM_PARAM_VARDIR  -  specifies  a  custom  path  to  directory  where  indexer  stores  data  when  using 
built-in  database  and  in  cache  mode.  By  default  /var  directory  of  mnoGoSearch  installation  is  used. 
Can  have  only  string  values.  The  parameter  is  available  in  PHP  4.1.0  or  later. 
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msql  (PHP  3,  PHP  4  >=  4.0.0) 


mSQL 


ejecuta  una  consulta  mSQL 

int  msql  (string  database ,  string  query,  int  link_identifier ) 


Devuelve  un  identificador  de  consulta  mSQL  positivo  en  el  resultado  de  la  consulta,  o  false  en  caso  de 
error. 

msql()  selecciona  una  base  de  datos  y  ejecuta  una  consulta  en  ella.  Si  no  se  especifica  el  identificador  de 
conexion  (link  identifier),  la  funcion  intentara  encontrar  una  conexion  abierta  en  el  servidor  mSQL  y  en 
el  caso  de  que  no  se  encontrase  intentara  crear  uno  como  si  se  llamase  a  msql_connect|3  sin  parametros 
(vease  msql_connectO). 


msql_affected_rows  (php  3>=  3.o.6,  php  4  >=  4.o.0) 

devuelve  el  numero  de  filas  involucradas 


int  msql_af fected_rows  (int  query_identifier) 


Devuelve  el  numero  de  filas  involucradas  ("tocadas")  por  una  consulta  especifica  (i.e.  el  numero  de  filas 
devueltas  por  una  SELECT,  el  numero  de  filas  modificadas  por  una  actualization  (update),  o  el  numero 
de  filas  suprimidas  por  una  elimination  (delete)). 

Vease  tambien:  msql_query ') 


msql_close  (PHP  3,  PHP  4  >=  4.0.0) 


cierra  una  conexion  mSQL 


int  msql_close  (int  link_identifier) 


Devuelve  true  si  tiene  exito,  false  en  caso  de  error. 

msql_close()  cierra  la  conexion  con  una  base  de  datos  mSQL  que  esta  asociada  con  el  identificador  de 
conexion  (link  identifier)  especificado.  Si  no  se  especifica  el  identificador  de  conexion,  se  asume  la 
ultima  conexion  abierta. 

Advierta  que  esto  no  es  necesario  habitualmente,  las  conexiones  abiertas  no-persistentes  son  cerradas 
automaticamente  a  la  conclusion  de  la  ejecucion  del  script. 
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Vease  tambien:  msql_connect')  y  msql  pcoimcct'). 
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msql_connect  (PHP  3,  PHP  4  >=  4.0.0) 

abre  una  conexion  mSQL 

int  msql_connect  (string  hostname) 

Devuelve  un  identificador  de  conexion  mSQL  positivo  si  tiene  exito,  o  false  en  caso  de  error. 

msql_connect()  establece  una  conexion  con  un  servidor  mSQL.  El  argumento  hostname  es  opcional,  y  en 
caso  de  que  falte,  se  asume  localhost. 

En  caso  de  que  se  haga  una  segunda  llamada  a  msql_connect()  con  los  mismos  argumentos,  no  se 
establece  una  nueva  conexion,  en  lugar  de  eso,  se  devuelve  el  identificador  de  conexion  ya  abierto. 

La  conexion  con  el  servidor  se  cerrara  tan  pronto  como  la  ejecucion  del  script  finalice,  a  menos  que  sea 
cerrada  antes  explfcitamente  por  una  llamada  a  msql  close  ). 

Vease  tambien:  msql_pconnectO,  msql_close'). 


msql_create_db  (php 3,  php 4 >=  4.o.0) 

crea  una  base  de  datos  mSQL 

int  msql_create_db  (string  database  name,  int  [link_identifier]) 

msql_create_db()  intenta  crear  una  base  de  datos  nueva  en  el  servidor  asociado  con  el  identificador  de 
conexion  (link  identifier)  especificado. 

Vease  tambien:  msql_drop_db  ). 

msql_createdb  (php 3,  php 4 >=  4.o.0) 

crea  una  base  de  datos  mSQL 

int  msql_createdb  (string  database  name,  int  [link_identifier]) 
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Identica  a  msql_create_db')- 


msql_data_seek  (PHP  3,  PHP  4  >=  4.0.0) 

desplaza  el  puntero  interno  de  fila 

int  msql_data_seek  (int  query_identifier,  int  row_number) 


Devuelve  true  si  tiene  exito,  false  en  caso  de  fallo. 

msql_data_seek()  desplaza  el  puntero  interno  de  fila  del  resultado  mSQL  asociado  con  el  identificador  de 
consulta  (query  identifier)  especificado  para  que  apunte  al  numero  de  fila  (row  number)  proporcionado. 
La  llamada  posterior  a  msql_fetch_mw ')  devolvera  esa  fila. 

Vease  tambien:  msql_fetch_row '). 


msql_dbname  <php 3,  php 4 >=  4 o 0) 

obtiene  el  nombre  de  la  base  de  datos  mSQL  actual 

string  msql_dbname  (int  query_identifier,  int  i) 


msql_dbname()  devuelve  el  nombre  de  base  de  datos  almacenado  en  la  posicion  i  del  puntero  devuelto 
desde  la  funcion  msql_listdbsO.  La  funcion  msql_numrows')  puede  utilizarse  para  determinar  cuantos 
nombres  de  base  de  datos  hay  disponibles. 


msql_drop_db  (php 3,  php 4 >=  4 o o> 

elimina  (suprime)  una  base  de  datos  mSQL 

int  msql_drop_db  (string  database_name,  int  link_identifier) 


Devuelve  true  si  tiene  exito,  false  en  caso  de  fallo. 

msql_drop_db()  intenta  eliminar  (suprimir)  una  base  de  datos  completa  del  servidor  asociado  con  el 
identificador  de  conexion  (link  identifier)  especificado. 

Vease  tambien:  msql_create_dbO- 
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mSQL 


elimina  (suprime)  una  base  de  datos  mSQL 
Vease  msql_drop_db(). 


msql_error  (php 3,  php 4 >=  4.0.0 

devuelve  el  mensaje  de  error  de  la  ultima  llamada  msql 

string  msql_error  () 

Los  errores  que  devuelve  el  servidor  de  base  de  datos  mSQL  no  dan  mucha  informacion  sobre  el 
problema.  Por  este  motivo,  utilice  estas  funciones  para  recuperar  la  cadena  de  caracteres  del  error. 


msql_fetch_array  (php  3  php  4  >=  4.0.0) 

recupera  una  fila  como  un  array 

int  msql_fetch_array  (int  query_identifier  [,  int  result_type] ) 

Devuelve  un  array  que  se  corresponde  con  la  fila  recuperada,  o  false  si  no  hay  mas  filas. 

msql_fetch_array()  es  una  version  ampliada  de  msql_fetch_row ')■  Ademas  de  almacenar  los  datos  en 
los  indices  numericos  del  array  resultado,  tambien  almacena  los  datos  en  indices  asociativos,  utilizando 
los  nombres  de  los  campos  como  claves. 

El  segundo  argumento  opcional  result_type  en  msql_fetch_array()  es  una  constante  y  puede  tomar 
los  valores  siguientes:  MSQL_ASSOC,  MSQL_NUM,  y  MYSQL_BOTH. 

Sea  precavido  si  esta  recuperando  resultados  de  una  consulta  que  puede  devolver  un  registro  que 
contiene  un  unico  campo  que  tiene  un  valor  de  0  (o  una  cadena  de  caracteres  vacfa,  o  null). 

Un  aspecto  importante  a  tener  en  cuenta  es  que  el  uso  de  msql_fetch_array()  NO  es  significativamente 
mas  lento  que  el  uso  de  msql_fetch_row '),  mientras  que  proporciona  un  valor  anadido  significativo. 

Para  detalles  adicionales,  vease  tambien  msql_fetch_row ') 
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msql_fetch_f  ield  (php  3,  PHP  4  >=  4.o.o) 

obtiene  information  de  campo 

object  msql_fetch_field  (int  query_identifier,  int  field_offset ) 


Devuelve  un  objeto  que  contiene  la  information  del  campo 

msql_fetch_field()  puede  utilizarse  para  obtener  information  sobre  campos  del  resultado  de  una 
consulta.  Si  no  se  especifica  el  desplazamiento  del  campo,  se  recupera  el  campo  siguiente  que  no  haya 
sido  aun  recuperado  por  msql_fetch_field(). 

Las  propiedades  del  objeto  son: 

•  name  -  nombre  de  la  columna 

•  table  -  nombre  de  la  tabla  a  la  que  pertenece  la  columna 

•  not_null  -  1  si  la  columna  no  puede  ser  nula 

•  primary _key  -  1  si  la  columna  es  una  clave  primaria 

•  unique  -  1  si  la  columna  es  una  clave  unica 

•  type  -  tipo  de  la  columna 

Vease  tambien  msql_field_seek')- 


msql_fetch_object  <php  3  php  4  >=  4.o.o) 

recupera  una  fila  como  un  objeto 

int  msql_fetch_ob ject  (int  query_identifier  [,  int  result_type] ) 


Devuelve  un  objeto  con  las  propiedades  que  corresponden  a  la  fila  recuperada,  o  false  si  no  hay  mas 
filas. 

msql_fetch_object()  es  similar  a  msql_fetch_array'),  con  una  diferencia  -  se  devuelve  un  objeto  en  vez 
de  un  array.  Indirectamente  esto  significa  que  solo  tiene  acceso  a  los  datos  por  los  nombres  de  los 
campos,  y  no  por  sus  desplazamientos  (los  numeros  son  nombres  de  propiedad  no  validos). 

El  segundo  parametro  optional  result_type  en  msql_fetch_array')  es  una  constante  y  puede  tomar 
los  valores  siguientes:  MSQL_ASSOC,  MSQL_NUM,  y  MSQL_BOTH. 

Resumiendo,  la  funcion  es  indentica  a  msql_fetch_arrayO,  y  casi  tan  rapida  como  msql_fetch_row()  (la 
diferencia  es  insignificante). 
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Vease  tambien:  msq  l_fetc  h_array ')  y  msql_fetch_row  ')- 


msql_fetch_row  (php  3,  php  4  >=  4 .0 .0) 

obtiene  una  fila  como  un  array  enumerado 

array  msql_fetch_row  (int  query_identifier) 


Devuelve  un  array  que  se  corresponde  con  la  fila  recuperada,  o  false  si  no  hay  mas  filas. 

msql_fetch_row()  recupera  una  fila  de  datos  del  resultado  asociado  con  el  identificador  de  consulta 
(query  identifier)  especificado.  La  fila  se  devuelve  en  un  array.  Cada  columna  devuelta  se  almacena  en  un 
desplazamiento  del  array,  comenzando  en  el  desplazamiento  0. 

Una  llamada  posterior  a  msql_fetch_row()  deverfa  devolver  la  fila  siguiente  del  conjunto  resultado,  o 
false  si  no  hay  mas  filas. 

Vease  tambien:  msq  Mete  h_array '),  msq  Mete  h_objecL),  msql_data_seel< '),  y  msql_result'). 


msql_f ieldname  (php 3,  php 4 >=  4.o.o) 


obtiene  el  nombre  del  campo 


string  msql_f ieldname  (int  query_identifier,  int  field) 


msql_fieldname()  devuelve  el  nombre  del  campo  especificado.  query_identifier  es  el 
identificador  de  consulta,  y  field  es  el  fndice  del  campo.  msql_f ieldname  ($result,  2)  ; 
devolvera  el  nombre  del  segundo  campo  del  resultado  asociado  con  el  identificador  result. 


msql_f ield_seek  (php  3  php  4  >=  4.o.0) 

establece  el  desplazamiento  del  campo 

int  msql_f ield_seek  (int  query_identifier,  int  field_offset) 


Se  posiciona  en  el  desplazamiento  de  campo  (field  offset)  especificado.  Si  la  siguiente  llamada  a 
msqlMetch_field')  no  incluye  un  desplazamiento  de  campo,  este  campo  sera  el  que  se  devuelva. 
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Vease  tambien:  msql_fetch_field(). 


msql_f ieldtable  (php 3,  php 4 >=  4.o.o) 

obtiene  el  nombre  de  la  tabla  de  un  campo 

int  msql_f ieldtable  (int  query_identifier,  int  field) 


Devuelve  el  nombre  de  la  tabla  desde  la  que  se  ha  recuperado  el  campo  (field) 


msql_f ieldtype  <php  3,  php  4  >=  4.o.0) 

obtiene  el  tipo  del  campo 

string  msql_f ieldtype  (int  query_identifier,  int  i) 


msql_fieldtype()  es  similar  a  la  funcion  msqlficldname').  Los  argumentos  son  identicos,  pero  se 
devuelve  el  tipo  del  campo.  Este  sera  "int",  "char"  o  "real". 


msql_f  ieldf  lags  (php  3  PHP  4  >=  4  o  o> 

obtiene  los  flags  del  campo 

string  msql_f ieldf lags  (int  query_identifier,  int  i) 


msql_fieldflags()  obtiene  los  flags  del  campo  (field)  especificado.  Actualmente  pueden  ser,  "not  null", 
"primary  key",  una  combinacion  de  ambos,  o  ""  (cadena  vacfa). 


msql_f ieldlen  (php 3  php 4 >=  4 o 0) 

obtiene  la  longitud  del  campo 

int  msql_f ieldlen  (int  query_identifier,  int  i) 
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msql_fieldlen()  devuelve  la  longitud  del  campo  especificado. 


msq  l_f  ree_resu  It  (php  3,  php  4  >=  4.0.o) 


libera  la  memoria  del  resultado 


int  msql_free_result  (int  query_identifier) 


msql_free_result()  libera  la  memoria  asociada  con  query_identifier.  Cuando  PHP  completa  una 
peticion,  esta  memoria  es  liberada  automaticamente,  por  este  motivo  solo  es  necesario  llamar  a  esta 
funcion  cuando  se  desea  estar  seguro  de  que  no  se  utiliza  demasiada  memoria  mientras  se  esta 
ejecutando  el  script. 


msq l_f  reeresu It  (php  3,  php  4  >=  4.0.o) 


libera  la  memoria  del  resultado 


Vease  msql_free_resultO 


msql_list_f ields  <php 3  php 4 >=  4.0.o) 


lista  los  campos  del  resultado 


int  msql_list_f ields  (string  database,  string  tablename) 


msql_list_fields()  recupera  information  sobre  el  nombre  de  tabla  (tablename)  dado.  Los  argumentos  son 
el  nombre  de  la  base  de  datos  (database  name)  y  el  nombre  de  la  tabla  (table  name).  Se  devuelve  un 
puntero  al  resultado  que  puede  utilizarse  con  msqLfieldtiags '),  msql_fieldlcn '),  msql_fieldname(),  y 
msql_fiekltype').  Un  indetificador  de  consulta  (query  identifier)  es  un  entero  positivo.  La  funcion 
devuelve  -1  si  ocurre  un  error.  En  $phperrmsg  se  almacena  una  cadena  de  caracteres  describiendo  el 
error,  y  a  menos  que  la  funcion  sea  llamada  como  @msql_list_f  ields  ( )  esta  cadena  de  error  puede 
ser  impresa. 

Vease  tambien  msql  error'j. 
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lista  los  campos  del  resultado 
Vease  msql_list_fieldsO- 


msql_list_dbs  (PHP  3,  PHP  4  >=  4.0.0) 

lista  las  bases  de  datos  mSQL  en  el  servidor 
int  msql_list_dbs (void)  ; 


msql_list_dbs()  devolvera  un  puntero  al  resultado  que  contiene  las  bases  de  datos  disponibles  desde  el 
daemon  msql  en  uso.  Utilice  la  funcion  msql_dbname()  para  recorrer  este  puntero. 


msqljistdbs  (PHP  3,  PHP  4  >=  4.0.0) 

lista  las  bases  de  datos  mSQL  en  el  servidor 
Vease  msql  list  dhs '). 

msq l_l ist_tables  (php  3  php  4  >=  4  0  0 

lista  las  tablas  de  una  base  de  datos  mSQL 

int  msql_list_tables  (string  database) 

msql_list_tables()  toma  un  nombre  de  base  de  datos  y  devuelve  un  puntero  similar  al  de  la  funcion 
msqlO  La  funcion  msql_tablename ')  deberia  utilizarse  para  obtener  los  nombres  reales  de  las  tablas  del 
puntero  devuelto. 

msqljisttables  (php  3,  php  4  >=  4.0.0) 

lista  las  tablas  de  una  base  de  datos  mSQL 
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Vease  msql_list_tables'). 

msql_num_f  ields  (php 3,  php 4 >=  4 .0 .<» 

obtiene  el  numero  de  campos  de  un  resultado 

int  msql_num_f ields  (int  query_identifier) 

msql_num_fields()  devuelve  el  numero  de  campos  de  un  conjunto  resultado. 
Vease  tambien:  msql'),  msql_query'),  msql_fetch_field '),  y  msql_num_rowsO. 

msql_num_rows  <php 3  php 4 >=  4.0.0 

obtiene  el  numero  de  filas  de  un  resultado 

int  msql_num_rows  (int  query_ldentifier) 

msql_num_rows()  devuelve  el  numero  de  filas  de  un  conjunto  resultado. 

Vease  tambien:  msqr),  msql_query '),  y  msql_fetch_row'). 

msql_numf ields  <php 3  php 4 >=  4.0.0) 

obtiene  el  numero  de  campos  de  un  resultado 

int  msql_numf ields  (int  query_identifier) 

Identica  a  msql  num  ficlds '). 

msql_numrows  <php  3  php  4  >=  4  0  o> 

obtiene  el  numero  de  filas  en  el  resultado 
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int  msql_numrows (void) ; 


Identica  a  msql_num_rowsO. 


msql_pconnect (php 3,  php 4 >=  4 .0 .<» 

abre  una  conexion  mSQL  persistente 

int  msql_pconnect  (string  hostname) 


En  caso  de  exito  devuelve  un  identificador  de  conexion  mSQL  persistente  positivo,  o  false  en  caso  de 
error. 

msql_pconnect()  se  comporta  de  forma  similar  a  msqlcon  licet)  con  dos  diferencias  importantes. 

Primero,  cuando  se  conecta,  la  funcion  debe  intentar  primero  localizar  una  conexion  (persistente)  que  ya 
este  abierta  en  el  mismo  host.  Si  se  encuentra  uno,  se  devuelve  un  identificador  para  el  mismo  en  vez  de 
abrir  una  conexion  nueva. 

Segundo,  la  conexion  con  el  servidor  SQL  no  se  cerrara  cuando  la  ejecucion  del  script  finalice.  A1 
contrario,  la  conexion  permanecera  abierta  para  un  uso  futuro  ( msql_close  J  no  cerrara  las  conexiones 
abiertas  por  msql_pconnect()). 

Este  tipo  de  conexiones  son  por  ello  denominadas  ’persistentes’. 


msql_query  (php 3,  php 4 >=  4.o.o) 


envfa  una  consulta  mSQL 


int  msql_query  (string  query,  int  link_identifier) 


msql_query()  envfa  una  consulta  a  la  base  de  datos  activa  actual  en  el  servidor  que  esta  asociada  con  el 
identificador  de  conexion  (link  identifier)  especificado.  Si  no  se  especifica  el  identificador  de  conexion, 
se  asume  la  ultima  conexion  abierta.  Si  no  hay  ninguna  conexion  abierta,  la  funcion  intenta  establecer 
una  conexion  como  si  se  hubiera  llamado  a  msqlcon  nect  ),  y  la  utiliza. 

En  caso  de  exito  devuelve  un  identificador  de  consulta  mSQL  positivo,  o  false  en  caso  de  error. 
Vease  tambien:  msql(),  msql  select  db  ),  y  msql_connect(). 
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construye  una  expresion  regular  para  una  busqueda  que  no  distinga  mayusculas/minusculas 
Vease  sql_regcaseQ. 


msql_result  (PHP  3,  PHP  4  >=4.0.0) 


obtiene  datos  resultado 


int  msql_result  (int  query_identifier,  int  i, 


mixed  field) 


Devuelve  el  contenido  de  la  celda  en  la  fila  y  desplazamiento  del  conjunto  resultado  mSQL  especificado. 

msql_result()  devuelve  el  contenido  de  una  celda  de  un  conjunto  resultado  mSQL.  El  argumento  campo 
(field)  puede  ser  el  desplazamiento  del  campo,  el  nombre  del  campo,  o  el  nombre  de  la  tabla  punto 
nombre  del  campo  (nombretabla.nombrecampo).  Si  el  nombre  de  la  columna  tiene  un  alias  (’select  foo  as 
bar  from...’),  utilice  el  alias  en  vez  del  nombre  de  la  columna. 

Cuando  se  trabaja  con  conjuntos  de  resultados  grandes,  deberfa  considerar  el  uso  de  las  funciones  que 
recuperen  bias  completas  (especificadas  mas  abajo).  Como  estas  funciones  recuperan  el  contenido  de 
varias  celdas  en  una  unica  llamada  de  funcion,  son  MUCHO  mas  rapidas  que  msql_result().  Advierta 
tambien  que  especificar  un  desplazamiento  numerico  para  el  argumento  campo  (field)  es  mucho  mas 
rapido  que  especificar  un  argumento  nombrecampo  o  nombretabla.nombrecampo. 

Alternativas  de  alto-rendimiento  recomendadas:  msql_fetch_row'),  msql_fetch_arrayO,  y 
msql_fetch_obj  ect'j. 


msql_select_db  <php  3  php  4  >=  4.o.0) 


selecciona  una  base  de  datos  mSQL 


int  msql_select_db  (string  database_name ,  int  link_identifier) 


Devuelve  true  si  tiene  exito,  false  en  caso  contrario. 

msql_select_db()  establece  la  base  de  datos  activa  actual  en  el  servidor  que  esta  asociada  con  el 
identificador  de  conexion  (link  identifier)  suministrado.  Si  no  se  especifica  el  identificador  de  conexion, 
se  asumne  la  ultima  conexion  abierta.  Si  no  hay  ninguna  conexion  abierta  la  funcion  intentara  establecer 
una  conexion  como  si  se  hubiera  llamado  a  sql_connect(),  y  la  utiliza. 

Cada  llamada  posterior  a  msql_query ')  se  hara  en  la  base  de  datos  activa. 
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Vease  tambien:  msql_connect '),  msql_pconnect'),  y  msql_query '). 


msql_selectdb  (php 3,  php 4 >=  4.0.0 


selecciona  una  base  de  datos  mSQL 
Vease  msql_select_db '). 


msql_tablename  (php 3,  php 4 >=  4.0.0 


obtiene  el  nombre  de  la  tabla  de  un  campo 


string  msql_tablename  (int  query_identifier,  int  field) 


msql_tablename()  toma  un  puntero  resultado  devuelto  por  la  funcion  msql_list_tablesO  como  un  rndice 
entero  y  devuelve  el  nombre  de  una  tabla.  La  funcion  msql_numrows ')  puede  utilizarse  para  determinar 
el  numero  de  tablas  del  puntero  resultado. 

Ejemplo  1.  msql_tablename()  example 


<?php 

msql_connect  ( "localhost " )  ; 

$result  =  msql_list_tables ( "Wisconsin" ) ; 

$i  =  0; 

while  ($i  <  msql_numrows ( $result ) )  { 

$tb_names [ $i ]  =  msql_tablename ( $result ,  $i) ; 
echo  $tb_naraes [ $i ]  .  "<BR>"; 

$i  +  +  ; 

} 

?> 
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LV.  Funciones  MySQL 

Estas  funciones  le  permiten  acceder  a  servidores  de  bases  de  datos  MySQL. 
Puede  encontrar  mas  informacion  sobre  MySQL  en  http://www.mysql.com/. 
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mysql_affected_rows  (php  3,  php  4  >=  4 .0 .0 

Devuelve  el  numero  de  filas  afectadas  de  la  ultima  operation  MySQL 

int  mysql_af fected_rows  (int  [identificador_de_enlace]) 


mysql_affected_rows()  devuelve  el  numero  de  filas  afectadas  en  la  ultima  sentencia  INSERT,  UPDATE 
o  DELETE  sobre  el  servidor  asociado  con  el  identificador  de  enlace  especificado.  Si  el  identificador  de 
enlace  no  ha  sido  especificado,  se  asume  por  defecto  el  ultimo  enlace. 

Si  la  ultima  sentencia  fue  un  DELETE  sin  clausula  WHERE,  todos  los  registros  han  sido  borrados  de  la 
tabla  pero  esta  funcion  devolvera  cero. 

Este  comando  no  es  efectivo  para  las  sentencias  SELECT,  sino  solo  para  las  sentencias  que  modifican 
registros.  Para  conseguir  el  numero  de  lineas  devueltos  por  un  SELECT,  usar  mysql_num_rows'). 


mysql_change_user  (php  3>=  3 .0  ,i3> 


Cambia  el  usuario  conectado  en  la  conexion  activa 


int  mysql_change_user  (string  usuario,  string  password,  string 
[base_de_datos] ,  int  [ identificador_de_enlace ]) 


mysql_change_user()  cambia  el  usuario  conectado  en  la  actual  conexion  activa,  o  si  se  especifica,  en  la 
conexion  determinada  por  el  identificador  de  enlace.  Si  se  especifica  la  base  de  datos,  esta  sera  la  base 
por  defecto  despues  del  cambio  de  usuario.  Si  la  nueva  combination  de  usuario/  password  no  esta 
autorizada,  el  usuario  actualmente  conectado  permanece  activo. 

Nota:  Esta  funcion  fue  introducida  en  PHP  3.0.1 3  y  requiere  MySQL  3.23.3  o  superior. 


mysql_close  (PHP  3,  PHP  4  >=  4.0.0) 

cierra  el  enlace  con  MySQL 

int  mysql_close  (int  [ identificador_de_enlace ]) 


Devuelve:  verdadero  si  exito,  falso  si  error. 
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mysql_close()  cierra  el  enlace  con  la  base  MySQL  que  esta  asociada  con  el  identificador  de  enlace 
especificado.  Si  no  se  especifica  el  identificador  de  enlace,  se  asume  por  defecto  el  ultimo  enlace. 

Nota:  Normalmente  no  es  necesario  ya  que  la  aperturas  no-persistentes  son  cerradas 
automaticamente  al  final  de  la  ejecucion  del  script. 


mysql  closel )  no  cerrara  los  enlaces  persistentes  generados  con  mysql_pconnect '). 

Ejemplo  1.  Ejemplo  de  MySQL  close 

<?php 

$link  =  mysql_connect  ("kraemer",  "marliesle",  "secret")  { 
or  die  ("Could  not  connect"); 

} 

print  ("Connected  successfully"); 
mysql_close  ($link) ; 

?> 


Ver  tambien:  mysql_conncct'),  y  mysqLpconncct'j. 


mysql_connect  (php  3  php  4  >=  4.0.0 


Abre  una  conexion  a  un  servidor  MySQL 

int  mysql_connect  (string  [hostname  [ : puerto]  [ : /camino/al/socket ] ]  ,  string 
[usuario] ,  string  [password]) 


Devuelve:  Un  identificador  de  enlace  positivo  si  tiene  exito,  o  falso  si  error. 

mysql_connect()establece  una  conexion  a  un  servidor  MySQL.  Todos  los  argumentos  son  opcionales,  y 
si  no  hay  ,  se  asumen  los  valores  por  defecto  (’localhost’,  usuario  propietario  del  proceso  del  servidor, 
password  vacia). 

El  hostname  puede  incluir  tambien  un  numero  de  puerto  .  ej.  "hostname:puerto"  o  un  camino  al  socket  ej. 
":/camino/al/socket"  para  localhost. 

Nota:  Soporte  para  ":puerto"  fue  anadido  en  PHP  3.0B4. 

Soporte  para  ":/camino/al/socket"  fue  anadido  en  PHP  3.0.10. 


En  el  caso  de  que  se  haga  una  llamada  a  mysql_connect()  con  los  mismos  argumentos,  no  se  establecera 
un  nuevo  enlace,  sino  que  se  devolvera  el  enlace  ya  abierto. 
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El  enlace  al  servidor  sera  cerrado  tan  pronto  como  la  ejecucion  del  script  finalice,  a  menos  que  se  cierre 
antes  explicitamente  llamando  a  mysql_close '). 

Ejemplo  1.  Ejemplo  de  MySQL  connect 


<?php 

$link  =  mysql_connect  ("kraemer",  "marliesle",  "secret")  { 
or  die  ("Could  not  connect"); 

} 

print  ("Connected  successfully"); 
mysql_close  ($link) ; 

?> 


Ver  tambien  :  mysql_pconnect '),  y  mysql_close '). 


mysql_create_db  (php  3  php  4  >=  4.0.0 


Crea  una  base  MySQL 


int  mysql_create__db  (string  base_de_datos ,  int  [identificador_de_enlace ]) 


mysql_create_db()  intenta  crear  una  base  nueva  en  el  servidor  asociado  al  identificador  de  enlace. 

Ejemplo  1.  Ejemplo  de  MySQL  create 


<?php 

$link  =  mysql_pconnect  ("kron",  "jutta",  "geheim")  { 
or  die  ("Could  not  connect"); 

} 

if  (mysql_create_db  ("my_db"))  { 

print  ("Database  created  successfullyXn" ) ; 

}  else  { 

printf  ("Error  creating  database:  %s\n",  mysql_error  ()); 


?> 


Por  razones  de  compatibilidad  puede  usarse  mysql_createdb()  igualmente. 
Ver  tambien:  mysq[_drop_db  J. 
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mysql_data_seek  (php  3  php  4  >=  4.0.0 


Mueve  el  puntero  interno 


int  mysql_data_seek  (int  id_resultado,  int  numero_de_fila) 


Devuelve:  verdadero  si  exito,  falso  si  error. 

mysql_data_seek()  mueve  el  puntero  de  fila  interno  a  la  fila  especificada  para  el  identificador  de 
resultado.  La  proxima  llamada  a  mysq l_fetch_row ')  devolvera  esa  fila. 

numero_de_fila  empieza  en  0. 

Ejemplo  1.  Ejemplo  de  MySQL  data  seek 

<?php 

$link  =  mysql_pconnect  ("kron",  "jutta",  "geheim")  { 
or  die  ("Could  not  connect"); 

} 

mysql_select_db  ("samp_db")  { 

or  die  ("Could  not  select  database"); 

} 

$query  =  "SELECT  last_name,  first_name  FROM  friends"; 

$result  =  mysql_query  ($query)  { 
or  die  ("Query  failed"); 

} 

#  fetch  rows  in  reverse  order 

for  ($i  =  mysql_num_rows  ($result)  -  1;  $i  >=0;  $i — )  { 

if  ( !mysql_data_seek  ($result,  $i) )  { 

printf  ("Cannot  seek  to  row  %d\n",  $i); 
continue ; 

} 


if ( ! ($row  =  mysql_f etch_ob ject  ($result))) 
continue ; 

printf  ("%s  %s<BR>\n",  $row->last_name,  $row->first_name) ; 

} 

mysql_f ree_result  ($result); 
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mysql_db_query  (php  3,  PHP  4  >=  4.o.0) 


Envia  una  sentencia  MySQL  al  servidor 


int  mysql_db_query  (string  base_de_datos ,  string  sentencia,  int 
[ identificador_de_enlace ] ) 


Devuelve:  Un  identificador  de  resultado  positivo  o  falso  si  error. 

mysql_db_query()  selecciona  una  base  y  ejecuta  una  sentencia  en  ella.  Si  el  identificador  de  enlace  no 
ha  sido  especificado,  la  funcion  intenta  encontrar  un  enlace  abierto  al  servidor  MySQL  y  si  no  lo 
encuentra,  intetara  crear  uno  como  si  fuera  llamado  mysql_connectO  sin  argumentos 

Ver  tambiermysql_con  nect'). 

Por  razones  de  compatibilidad  puede  usarse  mysql()  igualmente. 


mysql_drop_db  <php  3,  PHP  4  >=  4.o.0) 


Borra  una  base  de  datos  MySQL 


int  mysql_drop_db  (string  base_de_datos ,  int  [identificador_de_enlace ]) 


Devuelve:  verdadero  si  exito,  falso  si  error. 

mysql_drop_db()  intenta  suprimir  una  base  de  datos  completa  del  servidor  asociado  al  identificador  de 
enlace. 

Ver  tambien:  mysql_create_db ').  Por  razones  de  compatibilidad  puede  usarse  mysql_dropdb() 
igualmente. 


mysql_errno  <php  3,  PHP  4  >=  4  o  0) 

Deuelve  el  numero  del  mensaje  de  error  de  la  ultima  operation  MySQL 

int  mysql_errno  (int  [identificador_de_enlace ]) 

Los  errores  devueltos  por  mySQL  no  indican  los  warnings.  Usar  estas  funciones  para  encontrar  el 
numero  de  error. 

<?php 
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mysql_connect ( "marliesle"  )  ; 

echo  mysql_errno ( ) " . mysql_error ( ) . "<BR>"; 

mysql_select_db ( "nonexistentdb" )  ; 

echo  mysql_errno ( ) " . mysql_error ( ) . "<BR>"; 

$conn  =  my sql_query (" SELECT  *  FROM  nonexistenttable" ) ; 
echo  mysql_errno ( ) " . mysql_error ( ) . "<BR>"; 

?> 


Ver  tambien:  mysql_crror  ') 


mysql_error  (php  3,  php  4  >=  4.0.0 


Devuelve  el  texto  del  mensaje  de  error  de  la  ultima  operacion  MySQL 


string  mysql_error  (int  [identificador_de_enlace]) 


Los  errores  devueltos  por  mySQL  no  indican  los  warnings.  Usar  estas  funciones  para  encontrar  el 
numero  de  error. 

<?php 

mysql_connect ( "marliesle" ) ; 

echo  mysql_errno ( ) " . mysql_error ( ) . "<BR>"; 

mysql_select_db ( "nonexistentdb"  )  ; 

echo  mysql_errno ( ) " . mysql_error ( ) . "<BR>"; 

$conn  =  my sql_query (" SELECT  *  FROM  nonexistenttable"); 
echo  mysql_errno ( ) " . mysql_error ( ) ."<BR>"; 

?> 


Ver  tambien:  mysql_errnoO 


mysql_fetch_array  (php  3  php  4  >=  4.0.0 

Extrae  la  fila  de  resultado  como  una  matriz  asociativa 


array  mysql_fetch_array  (int  id_resultado,  int  [ tipo_de_re suit  ado ] ) 


Devuelve  una  matriz  que  corresponde  a  la  sentencia  extraida,  o  falso  si  no  quedan  mas  filas. 
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mysql_fetch_array()  es  una  version  extendida  de  mysql_fetch_row')-  Ademas  de  guardar  los  datos  en  el 
indice  numerico  de  la  matriz,  guarda  tambien  los  datos  en  los  indices  asociativos,  usando  el  nombre  de 
campo  como  clave. 

Si  dos  o  mas  columnas  del  resultado  tienen  el  mismo  nombre  de  campo,  la  ultima  columna  toma  la 
prioridad.  Para  acceder  a  la(s)  otra(s)  columna(s)  con  el  mismo  nombre,  se  debe  escificar  el  indice 
numerico  o  definir  un  alias  para  la  columna. 

select  tl.fl  as  foo  t2 . f 1  as  bar  from  tl,  t2 


La  funcion  mysql_fetch_array()  no  es  significativemente  mas  lenta  que  mysq  l_fetch_row '),  sin 
embargo  tiene  un  valor  anadido  importante. 

El  segundo  argumento  opcional  tipo_de_resultado  en  mysql_fetch_array()  es  una  constante  y 
puede  tomar  los  valores  siguientes:  MYSQL_ASSOC,  MYSQL_NUM,  y  MYSQL_BOTH.  (Esta 
funcionalidad  fue  anadida  en  PHP  3.0.7) 

Para  mas  detalles,  ver  tambien  mysql_fetch_rowO- 

Ejemplo  1.  mysql  fetch  array 


<?php 

mysql_connect ($host, $user, $password) ; 

$result  =  mysql_db_query ( "database" select  *  from  table"); 
while ($row  =  mysql_f etch_array ( $result ) )  { 

echo  $row [ "user_id" ] ; 
echo  $row [ " fullname " ] ; 

} 

mysql_f ree_result ($result) ; 

?> 


mysql_fetch_f ield  (php  3  php  4  >=  4.0.0 

Extrae  la  informacion  de  una  columna  y  la  devuelve  como  un  objeto. 

object  mysql_fetch_field  (int  id_resultado,  int  [salto]) 

Devuelve  un  objeto  que  contiene  la  informacion  del  campo. 

Puede  usarse  mysql_fetch_field()  para  obtener  informacion  sobre  campos  en  un  resultado.  Si  no  se 
especifica  el  salto,  se  extrae  el  siguiente  campo  que  todavia  no  ha  sido  extraido.  con  mysql_fetch_field(). 

Las  propiedades  del  objeto  son: 
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•  name  -  nombre  de  la  columna 

•  table  -  name  de  la  tabla  a  la  que  pertenece  la  columna 

•  max_length  -  longitud  maxima  de  la  columna 

•  not_null  -  1  si  la  columna  no  puede  contener  un  valor  nulo 

•  primary _key  -  1  si  la  columna  es  clave  primaria 

•  unique_key  -  1  si  la  columna  es  clave  unica 

•  multiple_key  -  1  si  la  columna  es  clave  no  unica 

•  numeric  -  1  si  la  columna  es  numerica 

•  blob  -  1  si  la  columna  es  un  BLOB 

•  type  -  el  tipo  de  la  columna 

•  unsigned  -  1  si  la  columna  es  unsigned 

•  zerofill  -  1  si  la  columna  es  zero-filled 

Ver  tambien  mysql_field_seek') 


mysql_fetch_lengths  (php 3,  php 4 >=  4.o.0) 


Devuelve  la  longitud  de  cada  salida  en  un  resultado 


array  mysql_fetch_lengths  (int  id_resultado ) 


Devuelve:  Una  matriz  que  contiene  las  longitudes  de  cada  campo  de  la  ultima  fila  extraida  por 
mysq  [_fetch_row '),  o  falso  si  error. 

mysql_fetch_lengths()  almacena  las  longitudes  de  cada  columna  en  la  ultima  fila  devuelta  por 
mysql_fetch_row'),  mysql_fetch_array '),  y  mysql_fetch_object ')  en  una  matriz,  empezando  por  0. 

Ver  tambien:  mysql_fetch_row '). 


mysql_fetch_object  (php  3,  php  4  >=  4.o.0) 


Extrae  una  fila  de  resultado  como  un  objeto 


object  mysql_fetch_ob ject  (int  id_resultado ,  int  [tipo_de_resultado] ) 
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Devuelve  un  objeto  con  las  propiedades  aur  corresponden  a  la  ultima  fila  extraida,  o  falso  si  no  quedan 
mas  filas. 

mysql_fetch_object()  es  similar  a  mysql_fetch_arrayO,  con  la  diferencia  que  un  objeto  es  devuelto  en 
lugar  de  una  matriz.  Indirectamente,  quiere  decir  que  solo  se  puede  aceder  a  los  datos  por  el  nombre  del 
campo,  y  no  por  su  posicion. 

El  argumento  opcional  tipo_de_resultado  es  una  constante  y  puede  tomar  los  valores  siguientes: 
MYSQL_ASSOC,  MYSQL_NUM,  y  MYSQL_BOTH. 

La  funcion  es  identica  a  mysq l_fetch_array '),  y  casi  tan  rapida  como  my sq l_fetc h_row ')  (la  diferencia  es 
insignificante). 

Ejemplo  1.  mysql  fetch  object 


<?php 

mysql_connect ($host,  $user,  $password)  ; 

$result  =  mysql_db_query ( "database" ,  " select  *  from  table"); 
while ($row  =  mysql_f etch_ob ject ($result) )  { 

echo  $row->user_id; 
echo  $row->fullname; 

} 

mysql_f ree_result ($result)  ; 

?> 


Ver  tambien:  mysql_fetch_array ')  y  mysq l_fetch_mw '). 


mysq l_f etc h  row  (php  3  php  4  >=  4  o  o> 


Devuelve  una  fila  de  resultado  como  matriz 


array  mysql_fetch_row  (int  id_resultado) 


Devuelve:  Una  matriz  que  corresponde  a  la  fila  selecionada,  o  falso  si  no  quedan  mas  lineas. 

mysql_fetch_row()  seleciona  una  fila  de  datos  del  resultado  asociado  al  identificador  de  resultado 
especificado.  La  fila  es  devuelta  como  una  matriz.  Cada  columna  del  resultdo  es  guardada  en  un  offset  de 
la  matriz,  empezando  por  el  offset  0. 

La  llamada  a  mysql_fetch_row()  deberfa  devolver  la  proxima  fila  del  resultado,  o  falso  si  no  quedan  mas 
filas. 

Ver  tambien:  mysql_fetch_array  [),  mysq l_fetch_object '),  mysq l_data_seel< ' j,  mysql_fetch_lengths'), 
and  mysql_resultO. 
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mysql_f ield_name  (php  3,  php  4  >=  4.o.o) 

Devuelve  el  nombre  del  campo  especificado  en  un  resultado 

string  mysql_f ield_name  (int  id_resultado ,  int  indice_del_campo ) 

mysql_field_name()  devuelve  el  nombre  del  campo  especificado.  Los  argumentos  de  la  funcion  son  el 
identificador  de  resultado  y  el  indice  del  campo.  Por  ejemplo:  mysql_f  ield_name  ($result ,  2 )  ; 

Devolvera  el  nombre  del  segundo  campo  asociado  al  identificador  de  resultado. 

Por  razones  de  compatibilidad  puede  usarse  tambien  mysql_fieldname(). 

mysql_f ield_seek  (php  3,  php  4  >=  4  o  o> 

Asigna  el  puntero  del  resultado  al  offset  del  campo  especificado 

int  mysql_f ield_seek  (int  id_resultado ,  int  offset_del_campo) 

Busca  el  offset  del  campo  especificado.  Si  la  proxima  llamada  a  mysql_fetch_fie[d ')  no  incluye  un  offset 
de  campo,  se  devolvera  ese  campo. 

Ver  tambien:  mysql_fetch_field''). 

mysql_f ield_table  <php  3  php  4  >=  4.o.c» 

Devuelve  el  nombre  de  la  tabla  donde  esta  el  campo  especificado 

string  mysql_f ield_table  (int  id_resultado,  int  offset_del_campo) 

Devuelve  el  nombre  de  la  tabla  del  campo.  Por  razones  de  compatibilidad  puede  usarse  tambien 

mysql_fieldtable() . 

mysql_f ield_type  (php  3  php  4  >=  4  o  o> 

Devuelve  el  tipo  del  campo  especificado  en  un  resultado 
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string  mysql_f ield_type  (int  id_resultado ,  int  offset_del_campo) 


mysql_field_type()  es  similar  a  la  funcion  mysql_field_name').  Los  argumentos  son  identicos,  pero  se 
devuelve  el  tipo  de  campo.  El  tipo  sera  "int",  "real",  "string",  "blob",  o  otros  detallados  en  la 
documentation  de  MySQL. 

Ejemplo  1.  mysql  field  types 

<?php 

mysql_connect ( "localhost : 3306" ) ; 
mysql_select_db ( "Wisconsin" ) ; 

$result  =  mysql_query ( "SELECT  *  FROM  onek") ; 

$fields  =  mysql_num_f ields ( Sresult ) ; 

$rows  =  mysql_num_rows ( $result ) ; 

$i  =  0; 

Stable  =  mysql_f ield_table ( Sresult ,  $ i )  ; 

echo  "Your  '".Stable."'  table  has  ".$f ields."  fields  and  ".$rows."  records  <BR>" 
echo  "The  table  has  the  following  fields  <BR>"; 
while  ($i  <  Sfields)  { 


Stype 

=  mysql_f ield_type 

(Sresult, 

$i)  ; 

Sname 

=  mysql_f ield_name 

(Sresult, 

$i)  ; 

Slen 

=  mysql_f ield_len 

(Sresult, 

Si) ; 

Sflags 

=  mysql_f ield_f lags 

(Sresult, 

Si) ; 

echo  Stype . "  ".Sname."  ".Slen."  ". Sflags . "<BR>" ; 
$i  +  t; 

} 

mysql_close ( ) ; 

?> 


Por  razones  de  compatibilidad  puede  usarse  tambien  mysql_fieldtype(). 


mysql_f i ield_f I lags  (php  3  php  4  >=  4.0.0 

Devuelve  los  flags  asociados  con  el  campo  especificado  en  un  resultado 

string  mysql_f ield_f lags  (int  id_resultado,  int  offset_del_campo) 


mysql_field_flags()  devuelve  los  flags  del  campo  especificado.  Cada  flag  es  devuelto  como  una  palabra  y 
estan  separados  un  unico  espacio,  se  puede  dividir  el  resultado  devuelto  utilizando  explode  ). 

Los  siguientes  flags  pueden  ser  devueltos  si  tu  version  de  MySQL  los  soporta:  "not_null", 

"primary _key",  "unique_key",  "multiple_key",  "blob",  "unsigned",  "zerofill",  "binary",  "enum", 
"auto_increment",  "timestamp". 
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Por  razones  de  compatibilidad  puede  usarse  tambien  mysql_fieldflags(). 


mysql_f ield  Jen  {php  3,  php  4  >=  4.0.0 

Devuelve  la  longitud  del  campo  especificado 

int  mysql_f ield_len  (int  id_resultado,  int  offset_del_campo) 


mysql_field_len()  devuelve  la  longitud  del  campo  especificado.  Por  razones  de  compatibilidad  puede 
usarse  tambien  mysql_fieldlen(). 


mysql  Jree_result  (php 3,  php 4 >=  4.0.0 

Libera  la  memoria  del  resultado 

int  mysql_free_result  (int  id_resultado) 


mysql_free_result()  solo  necesita  ser  llamada  si  te  preocupa  usar  demasiado  memoria  durante  la 
ejecucion  de  tu  script.  Toda  la  memoria  del  resultado  especificado  en  el  parametro  del  identificador  de 
resultado  sera  automaticamente  liberada. 

Por  razones  de  compatibilidad  puede  usarse  tambien  mysql_freeresult(). 


mysq I J nsert Jd  (php  3  php  4  >=  4.0.0 

Devuelve  el  identificador  generado  en  la  ultima  llamada  a  INSERT 

int  mysql_insert_id  (int  [identificador_de_enlace ]) 


mysql_insert_id()  devuelve  el  identificador  generado  para  un  campo  de  tipo  AUTO_INCREMENTED. 
Se  devolvera  el  identificador  genrado  por  el  ultimo  INSERT  para  el  identificador_de_enlace. 
Si  no  se  especifica  el  identificador_de_enlace,  se  asume  por  defecto  el  ultimo  enlace  abierto. 
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mysql_list_f ields  (php 3,  php 4 >=  4.o.o) 


Lista  los  campos  del  resultado  de  MySQL 


int  mysql_list_f ields  (string  base_de_datos ,  string  tabla,  int 
[identificador_de_enlace ] ) 


mysql_list_fields()  lista  information  sobre  la  tabla.  Los  argumentos  son  la  base  de  datos  y  el  nombre  de 
la  tabla.  Se  devuelve  un  puntero  que  puede  ser  usado  por  las  funciones  mysql_field_flagsO, 
mysql_field_len '),  mysql_field_nameO,  y  mysql_field_typeO- 

Un  identificador  de  resultado  es  un  entero  positivo.  La  funcion  devuelve  -1  si  se  produce  un  error.  Una 
cadena  de  caracteres  describiendo  el  error  sera  introducida  en  $phperrmsg,  y  a  menos  que  la  funcion 
sea  llamada  como  Smysql  ( )  el  literal  del  error  tambien  sera  impreso. 

Por  razones  de  compatibilidad  puede  usarse  tambien  mysql_listfields(). 


mysq  l_l  ist_d  bs  (php  3,  php  4  >=  4 .0 .0 

Lista  las  bases  de  datos  disponibles  en  el  servidor  MySQL 

int  mysql_list_dbs  (int  [identificador_de_enlace]) 

mysql_list_dbs()  devuelve  un  puntero  de  resultado  que  contiene  las  bases  disponibles  en  el  actual 
demonio  mysql.  Utiliza  la  funcion  mysql_tablename  )  para  explotar  el  puntero  de  resultado. 

Por  razones  de  compatibilidad  puede  usarse  tambien  mysql_listdbs(). 


mysql_list_tables  <php 3  php 4 >=  4 0  o> 


Lista  las  tablas  en  una  base  de  datos  MySQL 


int  mysql_list_tables  (string  base_de_datos ,  int  [identificador_de_enlace ]) 


mysql  list  tablesO  toma  el  nombre  de  la  base  y  devuelve  un  puntero  de  resultado  como  la  funcion 
mysql_db_query ').  La  funcion  mysql_tablename  )  debe  ser  usada  para  extraer  los  nombres  de  las  tablas 
del  puntero. 

Por  razones  de  compatibilidad  puede  usarse  tambien  mysql_listtables().  can  also  be  used. 


735 


MySQL 


mysql_num_f ields  (php 3,  php 4 >=  4.o.0) 

devuelve  el  numero  de  campos  de  un  resultado 

int  mysql_num_f ields  (int  id_resultado) 

mysql_num_fields()  devuelve  el  numero  de  campos  de  un  identificador  de  resultado. 

Ver  tambien:  mysql_db_queryO,  mysql_query '),  mysql_fetch_fie[d  ),  mysql_num_rows '). 
Por  razones  de  compatibilidad  puede  usarse  tambien  mysql_numfields(). 

mysql_num_rows  (php  3,  php  4  >=  4.o.0) 

Devuelve  el  numero  de  filas  de  un  resultado 

int  mysql_num_rows  (int  id_resultado) 

mysql_num_rows()  Devuelve  el  numero  de  filas  de  un  identificador  de  resultado. 

Ver  tambien:  mysql_db_query(),  mysqLquery ')  and,  mysql_fetch_row '). 

Por  razones  de  compatibilidad  puede  usarse  tambien  mysql_numrows(). 


mysql_pconnect  (php  3  PHP  4  >=  4  o  o> 


Abre  una  conexion  persistente  al  servidor  MySQL 

int  mysql_pconnect  (string  [hostname  [:puerto]  [ : /camino/al/socket ] ]  [, 

string  usuario  [,  string  password]]) 


Devuelve:  un  identificador  de  enlace  persistente,  o  falso  si  se  produce  un  error. 

mysql_pconnect( )  establece  una  conexion  a  un  servidor  MySQL.  Todos  los  argumentos  son  opcionales, 
y  si  no  existen,  se  asumen  los  valores  por  defecto  (’localhost’,  nombre  del  usuario  propietario  del 
proceso,  password  vacia). 

El  hostname  puede  incluir  un  numero  de  puerto.  ej.  "hostname:port"  o  un  camino  al  socket  ej. 
":/camino/al/socket"  para  el  puerto  para  el  host  local. 

Nota:  Soporte  para  ":puerto"  fue  anadido  en  3.0B4. 
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Soporte  para  ":/camino/al/socket"  fue  anadido  en  3.0.10. 


mysql  pconnectl )  actua  como  mysql  connect'j  con  dos  diferencias  fundamentales. 

Primero,  durante  la  conexion,  la  funcion  intenta  primero  encontrar  un  enlace  persistente  abierto  con  el 
mismo  host,  usuario  y  password.  Si  lo  encuentra,  devuelve  el  identificador  de  enlace  en  lugar  de  abrir 
otra  conexion. 

Segundo,  la  conexion  no  sera  cerrado  cuando  acabe  la  ejecucion  del  script.  El  enlace  permanecera  abierta 
para  ser  usado  en  el  future  (mysql_close')  will  not  cierra  el  enlace  establecido  con  mysql_pconnect()). 

Este  tipo  de  enlaces  son  llamados  ’persistentes’. 


mysqLquery  (php  3,  php  4  >=  4 .0 .0) 

Envia  una  sentencia  SQL  a  MySQL 

int  mysql_query  (string  sentencia  [,  int  identificador_de_enlace ]) 


mysql  qiieryO  envia  una  sentencia  a  la  base  activa  en  el  servidor  asociado  al  identificador  de  enlace.  Si 
no  es  especificado  un  ±dentificador_de_enlace,  se  asumira  el  ultilmo  enlace  abierto.  Si  no  hay 
ningun  enlace  abierto,  la  funcion  intenta  estalecer  un  enlace  como  si  se  llamara  funcion  mysql_connect') 
sin  argumentos,  y  lo  utiliza. 

La  sentencia  no  puede  terminar  por  punto  y  coma. 

mysql_query()  devuelve  true  (no-cero)  o  false  para  indicar  si  la  sentencia  se  ha  ejecutado 
correctamente  o  no.  Un  valor  true  significa  que  la  sentencia  era  correcta  y  pudo  ser  ejecutada  en  el 
servidor.  No  indica  nada  sobre  el  numero  de  fila  devueltas.  Es  perfectamente  posible  que  la  sentencia  se 
ejecute  correctamente  pero  que  no  devuelve  ninguna  fila. 

La  siguiente  sentencia  es  invalida  sintacticamente,  asi  que  mysql_query()  falla  y  devuelve  false: 

Ejemplo  1.  mysql_query() 

<?php 

$ result  =  mysql_query  ("SELECT  *  WHERE  1=1") 
or  die  ("Invalid  query"); 

?> 


La  siguiente  sentencia  es  invalida  semanticamente  si  my_col  no  es  una  columna  de  la  tabla  my_tbl,  asi 
que  mysql_query()  falla  y  devuelve  false: 
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Ejemplo  2.  mysql_query() 


<?php 

$result  =  mysql_query  ("SELECT  my_col  FROM  my_tbl") 
or  die  ("Invalid  query"); 

?> 


mysql_query()  fallara  tambien  y  devolvera  false  si  no  se  tiene  el  permiso  de  acceso  a  la  tabla 
especificada  en  la  sentencia. 

Asumiendo  la  sentencia  tenga  exito,  se  puede  llamar  a  mysql_affected_rows ')  para  saber  cuantas  filas 
fueron  afectadas  (para  DELETE,  INSERT,  REPLACE,  o  UPDATE  )  Para  las  sentencias  SELECT, 
mvsql  qiieryO  devuelve  un  nuevo  identificador  de  resultado  que  se  puede  pasar  a  mysql  result  ). 
Cuando  se  acabe  de  utilizar  el  resultado,  se  pueden  liberal-  los  recursos  asociados  utilizando 
mysq  l_free_result). 

Ver  tambien:  mysql_affected_rows  [),  mysql_db_queryO,  mysql_free_resultO,  mysql_result '), 
mysql_select_db  [),  and  mysql_connect '). 


mysql_result  (php  3,  php  4  >=  4.0.0 


Devuelve  datos  de  un  resultado 


int  mysql_result  (int  id_resultado,  int  numero_de_fila,  mixed  [campo]) 


mysql_result()  devuelve  el  contenido  de  una  celda  de  un  resultado  MySQL.  El  campo  argumento  puede 
ser  el  nombre  del  campo  o  el  offset  o  tabla.nombre_del_campo.  Si  el  nombre  de  la  columna  tiene  un 
alias  (’select  foo  as  bar  from...’),  utilice  el  alias  en  lugar  del  nombre  de  la  columna. 

Cuando  se  trabaja  un  un  gran  resultado,  debe  considerarse  la  utilizacion  de  una  funcion  que  devuelva  una 
fila  entera  ya  que  estas  funciones  son  MUCHO  mas  rapidas  que  mysql_result().  Tambien,  especificando 
un  offset  numerico  en  lugar  del  nombre  del  campo,  la  ejecucion  sera  mas  rapida. 

Las  llamadas  a  mysql_result()  no  deben  mezclarse  con  llamadas  a  las  otras  sentencias  que  trabajan  con 
un  identificador  de  resultado. 

Alternativas  recomendadas:  mysql_fetch_row  3,  mysq I  fetc h  array '),  y  mysq l_fetch_object ')■ 


mysqLselect_db  (php 3,  php 4 >=  4 o o 


Selecciona  un  base  de  datos  MySQL 


int  mysql_select_db  (string  base_de_datos ,  int  [identificador_de_enlace ]) 
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Devuelve  :  true  si  exito,  false  si  error. 

mysql  select  cl  b( )  establece  la  base  activa  que  estara  asociada  con  el  identificador  de  enlace 
especificado.  Si  no  se  especifica  un  identificador  de  enlace,  se  asume  el  ultimo  enlace  abierto.  Si  no  hay 
ningun  enlace  abierto,  la  funcion  intentara  establecer  un  enlace  como  si  se  llamara  a  mysqlconncct). 

Toda  llamada  posterior  a  mysql_query')  utilizara  la  base  activada. 

Ver  tambien:  mysql_conncct'j,  mysql  pconncct  ),  and  mysql_query '). 

Por  razones  de  compatibilidad  puede  usarse  tambien  mysql_selectdb(). 


mysqLtablename  (php 3  php 4 >=  4 .0 ,0) 


Devuelve  el  nombre  de  la  tabla  de  un  campo 


string  mysql_tablename  (int  id_resultado,  int  i) 


mysql_tablename()  toma  un  puntero  de  resultado  devuelto  por  mysql_list_tables')  asi  como  un  indice 
(integer)  y  devuelve  el  nomnre  de  una  tabla.  Se  puede  usar  la  funcion  mysql_num_rows ')  para 
determinar  el  nombre  de  tablas  en  el  puntero  de  resultado. 

Ejemplo  1.  mysql_tablename()  Example 


<?php 

mysql_connect  (  " localhost  :  330 6  "  ) ; 

$result  =  mysql_list_tables  ("Wisconsin") ; 

$i  =  0; 

while  ($i  <  mysql_num_rows  ($result))  { 

$tb_names [ $i ]  =  mysql_tablename  (Sresult,  $i); 
echo  $tb_names [ $i ]  .  "<BR>"; 

$i  +  +  ; 

} 

?> 


739 


LVI.  Funciones  de  Red 


740 


checkdnsrr  (php 3  php 4 >=  4 .0 .0) 


Red 


Comprueba  registros  DNS  correspondientes  a  nombres  de  maquinas  en  Internet  o  direcciones  IP. 

int  checkdnsrr  (string  host  [,  string  type]) 

Busca  en  DNS  entradas  del  tipo  type  correspondientes  a  host.  Devuelve  verdadero  si  encuentra  algun 
registro;  devuelve  falso  si  no  encuentra  ninguno  o  sucedio  algun  error. 

type  puede  ser:  A,  MX,  NS,  SOA,  PTR,  CNAME,  o  ANY.  Por  defecto  es  MX. 

host  puede  ser  o  la  direccion  IP  de  la  forma  xxxx.xxxx.xxxx.xxxx  o  el  nombre  de  la  maquina. 

Ver  tambien  getmxrr'),  gethostbyaddrf),  get hostby name'),  gethostbynameP),  y  named(8)  en  las  paginas 
del  manual. 

closelog  (PHP  3,  PHP  4  >=4.0.0) 

cierra  la  conexion  con  el  logger  del  sistema 
int  closelog (void) ; 

closelogO  cierra  el  descriptor  que  se  esta  usando  para  escribir  en  el  logger  del  sistema.  El  uso  de 
closelogO  es  opcional. 

debugger_off  (PHP3) 

deshabilita  el  depurador  interno  de  PHP 
int  debugger_off (void)  ; 

Deshabilita  el  depurador  interno  de  PHP.  El  depurador  esta  aun  en  desarrollo. 

debugger_on(PHP3) 

habilita  el  depurador  interno  de  PHP 


741 


Red 


int  debugger_on  (string  address ) 


Habilita  el  depurador  interno  de  PHP,  conectandolo  a  address.  El  depurador  esta  aun  en  desarrollo. 


fsockopen  (PHP  3,  PHP  4  >=  4.0.0) 


Abre  una  conexion  de  dominio  Internet  o  Unix  via  sockets. 

int  fsockopen  (string  hostname,  int  port  [,  int  errno  [,  string  errstr  [, 
double  timeout] ] ] ) 


Inicia  una  conexion  de  dominio  Internet  (AF_INET)  o  Unix  (AF_UNIX).  Para  el  domino  Internet,  abrira 
una  conexion  TCP  hacia  el  ordenador  hostname  en  el  puerto  port.  Para  el  dominio  Unix,  hostname 
se  usara  como  ruta  al  socket,  port  debe  ser  0  para  este  caso.  El  parametro  opcional  timeout  se  puede 
usar  para  especificar  un  timeout  en  segundos  para  establecer  la  conexion. 

fsockopen()  devuelve  un  puntero  a  fichero,  el  cual  se  puede  usar  junto  con  las  otras  funciones  de  ficheros 
(como  fgets)),  fgetssj),  fputsj),  fclose  '),  feof  ()). 

Si  la  llamada  falla,  esta  devolvera  falso  y  si  los  parametros  opcionales  errno  y  errstr  estan 
presentes,  indicaran  el  error  del  sistema  que  ocurrio  en  la  llamada  connect().  Si  errno  es  0  y  la  funcion 
devolvia  falso,  nos  indica  que  el  error  ocurrio  antes  de  la  llamada  connect().  Esto  es  debido 
principalmente  a  problemas  inicializando  el  socket.  Observe  que  los  argumentos  errno  y  errstr  deben  ser 
pasados  por  referenda. 

Dependiendo  del  entorno,  el  dominio  Unix  o  el  parametro  opcional,  timeout  puede  no  estar  disponible. 

Por  defecto,  el  socket  sera  abierto  en  modo  de  bloqueo.  Puede  cambiarlo  a  modo  de  no  bloqueo  usando 
set_socl<et_blocl<ing  "). 

Ejemplo  1.  ejemplo  con  fsockopen 

$fp  =  fsockopen ( "www . php . net " ,  80,  &$errno,  &$errstr,  30); 
if  (  ! $fp)  { 

echo  "$errstr  ($errno) <br>\n" ; 

}  else  { 

fputs ($fp, "GET  /  HTTP / 1 . 0 \n\n " ) ; 
while (! feof ($fp) )  { 

echo  f gets ( $fp, 128 ) ; 

} 

fclose ( $  f p ) ; 

} 


Ver  tambien:  pfsockopcn ') 
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Red 


Obtiene  el  nombre  de  una  maquina  en  Internet  mediante  su  direccion  IP. 

string  gethostbyaddr  (string  ip_address) 

Devuelve  el  nombre  del  ordenador  conectado  a  Internet  espeficado  por  el  parametro  ip_address.  Si 
ocurre  un  error,  devuelve  ip_address. 

Ver  tambien  gethostbyname'). 

gethostbyname  (php  3,  php  4  >=  4  o  0) 

Obtiene  la  direccion  IP  correspondiente  al  nombre  de  una  maquina  conectada  a  Internet. 

string  gethostbyname  (string  hostname) 

Devuelve  la  direccion  IP  de  una  maquina  conectada  a  Internet  especificada  por  hostname. 

Ver  tambien  gethostbyaddr '). 

gethostbynamel  (php  3,  php  4  >=  4  0  0) 

Obtiene  una  lista  de  direcciones  IP  correspondientea  a  los  nombres  de  maquinas  conectadas  a  Internet. 

array  gethostbynamel  (string  hostname) 

Devuleve  una  lista  de  direcciones  IP  pertenecientes  a  ordenadores  especificados  por  hostname. 

Ver  tambien  gethostbynameO,  gethostbyaddr [),  checkdnsrr  ),  getmxrrO,  y  named(8)  en  las  paginas  del 
manual. 

getmxrr  (PHP  3,  PHP  4  >=4.0.0) 

Obtiene  registros  MX  correspondientes  a  una  maquina  conectada  a  Internet. 

int  getmxrr  (string  hostname,  array  mxhosts  [,  array  weight]) 
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Busca  DNS  de  registros  MX  correspondientes  a  hostname.  Devuelve  verdadero  si  encuentra  alg£n 
registro;  devuelve  falso  si  no  encuentra  ninguno  o  se  produce  un  error. 

La  lista  de  registros  MX  encontrados  se  colocan  en  el  array  mxhosts.  Si  se  proporciona  el  array 
weight ,  se  rellenara  con  la  information  obtenida. 

Ver  tambien  checkdnsrr  ),  gethostbyname 3,  gethostbynamel '),  gethostbyaddr'),  y  named(8)  de  las 
paginas  del  manual. 


getprotoby  name  (php  4  >=  4.0.c» 

Obtiene  el  n£mero  asociado  al  nombre  del  protocolo 

int  getprotobyname  (string  name) 


getprotobyname()  devuelve  el  n£mero  asociado  al  nombre  del  protocolo  name  del  fichero 
/etc/protocols.  Ver  tambien  getprotobynumber'). 


getprotobynumber  (php  4  >=  4.o.o) 

obtiene  el  nombre  asociado  al  n£mero  de  protocolo 

string  getprotobynumber  (int  number) 


getprotobynumber()  devuelve  el  nombre  del  protocolo  asociado  al  n  umber  del  protocolo  en  el  fichero 
/etc/protocols.  Ver  tambien  getprotobyname'). 


getservby  name  (php  4  >=  4.0.0 

obtiene  el  n£mero  del  puerto  asociado  al  servicio  Internet  especificado 

int  getservbyname  (string  service,  string  protocol) 


getservbynameO  devuelve  el  puerto  que  corresponde  al  service  especificado  por  el  protocol  en 
/etc/services,  protocol  puede  ser  tcp  o  udp.  Ver  tambien  getservbyport'). 
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Red 


obtiene  el  servicio  Internet  que  correspondiente  al  puerto  del  protocolo  especificado 

string  getservbyport  (int  port,  string  protocol) 


getservbyport()  delvuelve  el  servicio  Internet  asociado  al  port  para  el  protocol  especificado  en 
/etc/services,  protocol  puede  ser  tcp  o  udp.  Ver  tambien  getservbyname)). 


openlog  (PHP  3,  PHP  4  >=4.0.0) 

abre  una  conexion  con  el  logger  del  sistema 

int  openlog  (string  ident,  int  option,  int  facility ) 


openlogO  abre  una  conexion  con  el  logger  del  sistema.  La  cadena  ident  se  aOade  a  cada  mensaje.  Los 
valores  de  option  y  facility  se  exponen  en  la  siguiente  section.  El  uso  de  openlog!)  is  opcional; 
Esta  sera  llamada  automaticamente  por  syslogO  si  fuera  necesario,  en  este  caso  ident  valdra  por 
defecto  false.  Ver  tambien  syslogO  y  closelog)). 


pfsockopen  (PHP  3>=  3.0.7,  PHP  4  >=  4.0.0) 

Abre  conexiones  persistentes  de  dominio  Internet  o  Unix. 

int  pfsockopen  (string  hostname,  int  port  [,  int  errno  [,  string  errstr  [, 
int  timeout] ] ] ) 


Esta  funcion  se  comporta  exactamente  como  fsockopen ')  con  la  diferencia  que  la  conexion  no  se  cierra 
despues  de  que  termine  el  script.  Esta  es  la  version  persistente  de  fsockopen)). 


set_socket_blocking  (php  3  php  4  >=  4 ,0  .o> 

Set  blocking/non-blocking  modo  de  un  socket 

int  set_socket_blocking  (int  socket  descriptor ,  int  mode ) 
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Si  mode  es  falso,  el  socket  estara  descriptor  will  be  switched  to  non-blocking  mode,  y  si  es  true,  este 
pasara  a  modo  bloqueo.  Esto  afecta  a  llamadas  como  fgets ')  que  leen  del  socket.  En  el  modo  de 
no-bloqueo  una  llamada  fgets()  devolvera  la  informacion  en  el  acto,  mientras  que  en  modo  bloqueo 
esperara  a  que  la  informacion  este  disponible  en  el  socket. 


syslog  (PHP  3,  PHP  4  >=  4.0.0) 

genera  un  mensaje  de  sistema 

int  syslog  (int  priority ,  string  message) 


syslogO  genera  un  mensaje  que  sera  distribuido  por  el  logger  del  sistema.  priority  es  una 
combination  de  la  facility  y  el  level,  los  valores  se  indicaran  en  la  section  siguiente.  El  argumento 
restante  es  el  mensaje  a  enviar,  excepto  que  los  dos  caracteres  %m  sean  reemplazados  por  la  cadena  de 
error  (strerror)  correspondiente  al  valor  actual  de  errno. 

Mas  informacion  acerca  de  syslog  se  puede  encontrar  en  las  paginas  del  manual  en  equipos  Unix. 

En  Windows  NT,  el  servicio  syslog  es  emulado  usando  el  Log  de  Eventos. 
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odbc_autocommit  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 

Interruptor  de  comportamiento  de  auto-entrega 

int  odbc_autocommit  (int  connect ion_id  [,  int  OnOff]) 


Sin  el  parametro  OnOff,  esta  funcion  devuelve  el  estado  de  auto-entrega  para  connect  ion_id. 
Devuelve  true  si  auto-entrega  esta  habilitado,  y  false  si  no  lo  esta  o  ha  ocurrido  un  error. 

Si  OnOff  es  true,  auto-entrega  esta  activado,  si  es  false  auto-entrega  esta  desactivado.  Devuelve 
true  cuando  se  cumple,  false  cuando  falla. 

Por  defecto,  auto-entrega  es  para  una  conexion.  Desabilitar  auto-entrega  es  como  comenzar  una 
transaccion. 

Ver  tambien  odbc_commitO  y  odbc_rollback)). 


odbc_binmode  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 

Manejo  de  campos  de  datos  binarios 

int  odbc_binmode  (int  result_id ,  int  mode) 


(Elementos  afectados  ODBC  SQL:  BINARY,  VARBINARY,  LONGVARBINARY) 

•  ODBC_BINMODE_PASSTHRU:  Paso  a  traves  de  datos  binarios 

•  ODBC_BINMODE_RETURN:  Devuelve  como  es 

•  ODBC_BINMODE_CONVERT:  Devuelve  convertido  en  caracter 

Cuando  los  datos  binarios  en  SQL  son  convertidos  a  datos  caracter  en  C,  cada  byte  (8  bits)  de  datos 
fuente  es  representada  como  dos  caracteres  en  ASCII.  Esos  caracteres  son  la  representacion  en  ASCII  de 
los  numeros  en  su  forma  Hexadecimal.  Por  ejemplo,  un  00000001  binario  es  convertido  a  "01"  y  un 
11111111  binario  es  convertido  a  "  ff  " . 


Tabla  1.  Manejo  de  LONGVARBINARY 


modo  binario 

longreadlen 

resultado 

ODBC BINMODE PASSTHRU 

0 

passthru 

odbc binmode return 

0 

passthru 

ODBC BINMODE CONVERT 

0 

passthru 

ODBC BINMODE PASSTHRU 

0 

passthru 

ODBC_BINMODE_PASSTHRU 

>0 

passthru 

748 


ODBC 


modo  binario 

longreadlen 

resultado 

ODBC BINMODE RETURN 

>0 

Devuleve  como  es 

ODBC_BINMODE_CONVERT 

>0 

Devuelve  como  caracter 

Si  usamos  odbc_fetch_into'),  passthru  significara  que  una  cadena  vacia  es  devuelta  por  esas  campos. 

Si  result_id  es  0,  las  definiciones  se  aplican  por  defecto  para  nuevos  resultados. 

Nota:  Por  defecto,  longreadlen  es  4096  y  el  modo  binario  por  defecto  es  odbc_binmode_return.  El 
manejo  de  campos  binarias  largas  tambien  esta  afectado  por  odbcjongreadlen;) 


odbc_close  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 


Cierra  una  conexion  ODBC 


void  odbc_close  (int  connection_id) 


odbc_close()  cerrara  la  conexion  al  servidor  de  bases  datos  asociado  con  el  identificador  de  conexion 
dado. 

Nota:  Esta  funcion  fallara  si  hay  transacciones  abiertas  sobre  esta  conexion.  La  conexion  quedara 
abierta  en  ese  caso. 


odbc_close_all  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 

Cierra  todas  las  conexiones  ODBC 

void  odbc_close_all (void)  ; 

odbc_close_all()  cerrara  todas  las  conexiones  a  servidor(es)  de  bases  de  datos. 

Nota:  Esta  funcion  fallara  si  hay  transacciones  abiertas  sobre  esta  conexion.  La  conexion  quedara 
abierta  en  ese  caso. 
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odbc_commit  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 
Entrega  una  transaccion  ODBC 

int  odbc_commit  (int  connect ion_id) 


Devuelve:  true  si  la  operacion  se  realiza  con  exito,  false  si  falla.  Todas  las  transacciones  pendientes 
sobre  connection_id  son  entregadas. 


odbc_connect  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 


Conecta  a  una  fuente  de  datos 


int  odbc_connect  (string  dsn,  string  user,  string  password  [,  int 
cursor_type ] ) 


Devuelve  una  conexion  ODBC  id,  o  0  (false)  cuando  ocurre  un  error. 

La  conexion  id  devuelta  por  estas  funciones  es  necesaria  para  otras  funciones  ODBC.  Se  pueden  tener 
multiples  conexiones  abiertas  a  la  vez.  El  opcional  cuarto  parametro  asigna  el  tipo  de  cursor  que  va  a  ser 
usado  para  esta  conexion.  Este  parametro  normalmente  no  es  necesario,  pero  puede  ser  util  para  trabajar 
sobre  problemas  con  algunos  drivers  ODBC. 

Con  algunos  drivers  ODBC,  si  ejecutamos  un  procedimiento  complejo,  este  puede  fallar  con  un  error 
similar  a:  "Cannot  open  a  cursor  on  a  stored  procedure  that  has  anything  other  than  a  single  select 
statement  in  it".  Usando  SQL_CUR_USE_ODBC  se  puede  evitar  ese  error.  Algunos  drivers  tampoco 
soportan  el  parametro  row_number  en  odbc_fetch_row().  SQL_CUR_USE_ODBC  tambien  podria 
ayudar  en  ese  caso. 

Las  siguientes  constantes  son  definidas  por  tipos  de  cursor: 


•  SQL_CUR_USE_IF_NEEDED 

•  SQL_CUR_USE_ODBC 

•  SQL_CUR_USE_DRIVER 

•  SQL_CUR_DEFAULT 
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Para  conexiones  persistentes  ver  odbc_pconnect '). 


odbc_cursor  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 

Toma  un  nombre  de  cursor 

string  odbc_cursor  (int  result_id) 

odbc_cursor  devolvera  un  nombre  de  cursor  para  el  result_id  dado. 


odbc_do  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 

sinonimo  de  odbc_exec ') 

string  odbc_do  (int  conn_id,  string  query ) 

odbc_do  ejecutara  una  consulta  (query)  sobre  la  conexion  dada 


odbc_exec  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 

Prepara  o  ejecuta  una  declaracion  SQL 

int  odbc_exec  (int  connect ion_id ,  string  query_string) 

Devuelve  false  en  caso  de  error.  Devuelve  un  indetificador  ODBC  si  el  comando  SQL  fue  ejecutado 
satisfactoriamente. 

odbc_exec()  enviara  una  declaracion  SQL  al  servidor  de  bases  de  datos  specificado  por 
connection_id.  Este  parametro  debe  ser  un  indetificador  valido  devuelto  por  odbc_conncct()  o 
odbc_pconnect()  ■ 

Ver  tambien:  odbc_prepare ')  y  odbc_execute ')  para  ejecucion  multiple  de  declaraciones  SQL. 
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odbc_execute  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 

ejecuta  una  declaration  preparada 

int  odbc_execute  (int  result_id  [,  array  parameter s_array] ) 

Ejecuta  uan  declaration  preparada  con  odbc_prepare )).  Devuelve  true  cuando  la  ejecucion  es 
satisfactoria,  false  en  otro  caso.  Introducir  el  vector  arameters_array  solo  es  necesario  si 
realmente  tenemos  parametros  en  la  declaracion. 


odbc_fetch_into  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 

Busca  un  registro  de  resutados  dentro  de  un  vector 

int  odbc_fetch_into  (int  result_id  [,  int  rownumber,  array  result_array] ) 

Devuelve  el  numero  de  campos  en  el  resultado;  false  on  error.  result_array  debe  serpasado  por 
referenda,  pero  puede  ser  de  cualquier  tipo,  desde  este  sera  convertido  a  tipo  vector.  El  vector  contendra 
el  valor  de  campo  initial  empezando  en  indice  de  vector  0. 


odbc_fetch  row  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 


Busca  un  registro 


int  odbc_fetch_row  (int  result_id  [,  int  row_number] ) 


Si  odbc_fetch_row()  fue  succesful  (there  was  a  row),  true  is  returned.  If  there  are  no  more  rows, 
false  is  returned. 

odbc_fetch_row()  busca  un  registro  de  datos  que  fue  devuelta  por  odbc_do))  /  odbc_exec ').  Despues  de 
que  odbc_fetch_row()  sea  llamado,  se  puede  acceder  a  los  campos  de  este  registro  con  odbc_result '). 

Si  no  se  especifica  row_number ,  odbc_fetch_row()  intentara  buscar  el  siguiente  registro  en  los 
resultados.  Lamar  a  odbc_fetch_row()  con  o  sin  row_number  puede  ser  mezclado. 

Para  pasar  a  traves  del  resultado  mas  de  una  vez,  se  puede  llamar  a  odbc_fetch_row()  con  row_number 
1,  y  despues  continuar  haciendo  odbc_fetch_row()  sin  row_number  para  revisar  el  resultado.  Si  un 
driver  no  admitiese  busquedas  de  registros  por  numero,  el  parametro  row_number  seria  ignorado. 
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odbc_field_name  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 

Devuelve  el  nombre  de  campo 

string  odbc_f ieldname  (int  result_id,  int  field_number) 


odbc_field_name()  devolvera  el  nombre  del  campo  almacenado  en  el  numero  de  campo  elegido  dentro 
del  identificador  ODBC.  La  numeracion  de  campos  comienza  en  1.  En  caso  de  error  devolveria  false. 


odbc_field_type  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 

Tipo  de  datos  de  un  campo 

string  odbc_f ield_type  (int  result_id,  int  field_number) 


odbc_field_type()  Devolvera  el  tipo  SQL  de  un  campo  referenciado  por  numero  en  el  identificador 
ODBC,  identifier.  La  numeracion  de  campos  comienza  en  1. 


odbc_field_len  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 

Da  la  longitud  de  un  campo 

int  odbc_f ield_len  (int  result_id,  int  field_number) 


odbc_field_len()  devolvera  la  longitud  de  un  campo  referenciado  por  numero  en  un  identificador  ODBC 
La  numeracion  de  campos  comienza  en  1 . 


odbc_free_result  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 

recursos  fibres  asociados  con  un  resultado 

int  odbc_free_result  (int  result_id ) 


Always  returns  true. 
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odbc_free_result()  solo  necesita  ser  llamado  en  caso  de  preocupacion  por  demasiado  uso  de  memoria 
cuando  se  ejecuta  un  script.  Toda  la  memoria  resultante  quedara  automatic amente  liberada  cuando  el 
script  finalice.  Pero  si  es  seguro  que  no  se  vaya  a  necesitar  la  informacion  nada  mas  que  en  un  script,  se 
debera  llamar  a  la  funcion  odbc_free_result(),  y  la  memoria  asociada  con  result_id  sera  liberada. 


Nota:  Si  la  auto-entrega  no  esta  activada  la  (ver  odbc_autocommit;))  y  se  ejecuta 
odbc_free_result()  antes  de  la  entrega,  todo  queda  pendiente  de  las  transaciones  que  esten  en 
lista. 


odbc  Jongreadlen  (php  3>=  3.0.6,  php  4  >=  4.0.0 

manejo  de  LONGITUD  de  columnas 

int  odbc_longreadlen  (int  result_id,  int  length) 

(ODBC  SQL  tipos  relaccionados:  LONG,  LONGVARBINARY)  El  numero  de  bytes  devueltos  para  PHP 
es  controlado  por  el  parametro  length.  Si  es  asignado  a  0,  la  longitud  del  campo  es  pasado  al  cliente. 

Nota:  El  manejo  de  campos  LONGVARBINARY  tambien  esta  afectado  por  odbc_binmode;) 


odbc_num_fields  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 

numero  de  campos  de  un  resultado 

int  odbc_num_f ields  (int  result_id ) 


odbc_num_fields()  devolvera  el  numero  de  campos  dentro  de  un  ODBC.  Esta  funcion  devolvera  -1  en 
caso  de  error.  El  argumento  es  un  identificador  valido  devuelto  por  odbc_exec '). 


odbc_pconnect  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 

Abre  una  conexion  permanente  de  base  de  datos 
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int  odbc  pconnect  (string  dsn,  string  user,  string  password  [,  int 
cursor_type ] ) 


Devuelve  un  identificador  de  conexion  ODBC  o  0  (false)  en  caso  de  error.  Esta  funcion  es 
odbc_connectO,  excepto  que  la  conexion  no  sea  realmente  cerrada  cuando  el  script  ha  finalizado.  Las 
respuestas  futuras  para  una  conexion  con  la  misma  combinacion  dsn,  user,  password  (via 
odbc_connectO  y  odbc_pconnect())  puede  reusar  la  conexion  permanente. 


Nota:  Las  conexiones  permanentes  no  tienen  efecto  si  PHP  es  usado  como  programa  CGI. 


Para  informacion  acerca  del  paramentor  opcional  cursor_type  ver  la  funcion  odbc_connect ').  Para  mas 
informacion  sobre  conexiones  permanentes,  ir  al  apartado  PHP  FAQ. 


odbc_prepare  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 

Prepara  una  declaracion  para  su  ejecucion 

int  odbc  prepare  (int  connect ion_id,  string  query_string) 

Devuelve  false  en  caso  de  error. 

Devuelve  un  identificador  ODBC  si  el  comando  SQL  esta  preparado.  El  identificador  resultante  puede 
ser  usado  mas  tarde  para  ejecutar  la  declaracion  con  odbc_execute'). 


odbcnumrows  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 

Numero  de  campos  en  un  resultado 

int  odbc_num_rows  (int  result_id) 


odbc_num_rows()  devolvera  el  numero  de  registros  de  un  ODBC.  Esta  funcion  devolvera  -1  en  caso  de 
error.  Para  declaraciones  INSERT,  UPDATE  y  DELETE  odbc_num_rows()  devolvera  el  numero  de 
registros  afectados.  Para  una  clausula  SELECT  esta  puede  ser  el  numero  de  registros  permitidos. 

Nota:  El  uso  de  odbc_num_rows()  para  determinar  el  numero  de  registros  permitidos  despues  de  un 
SELECT  devolvera  - 1 . 
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odbc  result  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 


coge  information  de  un  campo 


string  odbc_result  (int  result_id,  mixed  field) 


Devuelve  el  contenido  de  un  campo. 

field  puede  ser  cualquier  contenido  del  campo  que  queramos;  o  puede  ser  una  cadena  que  contenga  el 
nombre  del  campo;  Por  ejemplo: 

$item_3  =  odbc_result ($Query_ID,  3  ); 

$item_val  =  odbc_result ($Query_ID,  "val"); 


La  primera  sentencia  odbc_result()  devuelve  el  valor  del  tercer  campo  detro  del  registro  actual  de  la  cola 
resultante.  La  segunda  funcion  llama  a  odbc_result()  y  devuelve  el  valor  de  un  campo  cuyo  nombre  es 
"val"  en  el  registro  actual  de  la  cola  resultante.  Ocurre  un  error  si  un  numero  de  columna  para  un  campo 
es  menor  que  uno  o  excede  el  numero  de  campos  en  el  registro  actual.  Similarmente,  ocurre  un  error  si 
un  campo  con  un  nombre  que  no  sea  uno  de  los  nombres  de  campo  de  una  talba  o  tablas  que  sea  o  sean 
encoladas. 

Los  indices  de  campo  comienzan  en  1.  Recordando  el  metodo  binario  de  campos  con  gran  information, 
es  devuleto  con  referencia  a  odbcjbinmode  ()  y  odbcjongreadlen)). 


odbc  result_all  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 


Print  result  as  HTML  table 


int  odbc_result_all  (int  result_id  [,  string  format ]) 


En  caso  de  error,  como  resultado,  devuelve  false. 

odbc_result_all()  Imprimira  todos  los  registros  de  un  identificador  prducidoo  por  odbc_exec0-  El 
resultado  es  impreso  en  una  tabla  formato  HTML.  Con  el  argumento  de  cadena  optional  format, 
ademas,  todas  los  formatos  de  tablas  pueden  ser  realizadas. 


odbc  rollback  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 


Volver  a  pasar  una  transacion 
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int  odbc_rollback  (int  connect ion_id) 


Vuelve  a  pasar  todas  las  declaraciones  pendientes  connect ion_id.  Devuelve  true  cuando  el 
resultado  es  satisfactorio,  false  cuando  no  lo  es. 


odbc_setoption  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 

Ajusta  la  configuracion  de  ODBC.  Devuelve  false  en  caso  de  error,  en  otro  caso  true. 

int  odbc_setoption  (int  id,  int  function,  int  option,  int  param) 


Esta  funcion  permite  buscar  las  opciones  ODBC  para  una  conexion  particular  o  consulta  resultante.  Esto 
esta  escrito  para  trabajar  sobre  problemas  en  peculiaries  drivers  ODBC.  Esta  funcion  Solo  se  deberia  usar 
siendo  un  programador  de  ODBC  y  entendiendo  los  efectos  que  las  opciones  tendran.  Debemos  tener  la 
certeza  de  que  necesitamos  una  buena  referencia  de  reference  to  explicar  todas  las  diferentes  opciones  y 
valores  que  pueden  ser  usados.  Las  diferentes  versiones  de  drivers  soportan  diferentes  opciones. 

Ya  que  los  efectos  pueden  variar  dependiendo  del  driver  ODBC,  deberiamos  usar  la  function  en  scripts 
para  ser  hecho  publico  lo  que  permitira  que  sea  fuertemente  desalentado.  Algunas  opciones  ODBC  no 
estan  permitidas  para  esta  funcion  porque  debe  ser  configurada  antes  de  que  la  conexion  sea  establecida 
o  la  consulta  este  preparada.  Sin  embargo,  si  un  determinado  trabajo  hace  la  tarea  de  PHP,  el  jefe  no 
contaria  con  nosotros  para  usar  un  producto  comercial,  esto  es  lo  que  realmente  suele  pasar. 

Id  es  una  coexion  id  o  resultado  id  sobre  la  que  cambiaremos  la  configuracion.  Para 
SQLSetConnectOptionO,  esta  es  una  conexion  id.  Para  SQLSetStmtOption(),  este  es  un  resultado  id. 

function  es  la  funcion  ODBC  a  usar.  El  valor  deberia  ser  1  para  SQLSetConnectOptionO  y  2  para 

SQLSetStmtOptionO- 

Parmeter  option  es  la  opcion  a  configurar. 

El  parametro  param  es  el  valor  para  la  escogida  opcion  option. 

Ejemplo  1.  Ejemplos  ODBC  Setoption 

//  1.  Option  102  of  SQLSetConnectOptionO  is  SQL_AUTOCOMMIT . 

//  Value  1  of  SQL_AUTOCOMMIT  is  SQL_AUTOCOMMIT_ON . 

//  Este  ejemplo  tiene  el  mismo  efecto  que 
//  odbc_autocommit ( $conn,  true) ; 

odbc_setoption  ($conn,  1,  102,  1) ; 

//  2.  Option  0  of  SQLSetStmtOptionO  is  SQL_QUERY_TIMEOUT . 

//  Este  ejemplo  asigna  el  tiempo  de  espera  de  la  consulta  a  30  segundos . 

$result  =  odbc_prepare  ($conn,  $sql)  ; 
odbc_setoption  ($result,  2,  0,  30); 
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odbc_execute  ($result); 
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LVIII.  Funciones  de  Oracle  8 


Estas  funciones  permiten  acceder  a  bases  de  datos  Oracle8  y  Oracle7.  Estas  usan  la  Oracle8 
Call-Interface  (OCI8).  Necesitara  las  librerias  clientes  de  Oracle8  para  usar  esta  extension. 

Esta  extension  es  mas  flexible  que  las  estandar  de  Oracle.  Soporta  el  enlace  de  variables  locales  y 
globales  de  PHP  con  placeholders  de  Oracle,  tiene  soporte  completo  para  LOB,  FILE  y  ROWID  y  le 
permiten  usar  las  variables  definidas  por  el  usuario. 
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OCIDefineByName  (PHP  3>=  3.0.7,  PHP  4  >=  4.0.0) 


OCI8 


Usa  una  variable  de  PHP  para  el  define-step  durante  una  sentencia  SELECT 

int  OCIDefineByName  (int  stmt ,  string  Column-Name,  mixed  Stvariable  [,  int 
type] ) 


OCIDelineByNameO  busca  el  valor  de  las  Columnas-SQL  dentro  de  variables  PHP  definidas  por  el 
usuario.  Cuidado  que  Oracle  nombra  todas  las  columnas  en  MAYUSCULAS,  mientras  que  en  su  select 
puede  usar  tambien  minusculas  write  lower-case.  OCIDelineByNameO  espera  que  Column-Name  este 
en  mayusculas.  Si  define  una  variable  que  no  existe  en  la  sentecia  SELECT,  no  se  producira  ningun  error. 

Si  necesita  definir  un  tipo  de  dato  abstracto  (LOB/ROWID/BFILE)  tendra  que  alojarlo  primero  usando  la 
funcion  OCINewDescriptor()  function.  Vea  tambien  la  funcion  OCIBindByName(). 

Ejemplo  1.  OCIDefineByName 

<?php 

/*  OCIDef ineByPos  example  thies@digicol.de  (980219)  */ 

$conn  =  OCILogon (" scott ", "tiger ") ; 

$stmt  =  OCIParse  ( $conn, " select  empno,  ename  from  emp"); 

/*  la  definicion  DEBE  hacerse  ANTES  del  ociexecute !  */ 

OCIDefineByName ( $stmt , "EMPNO"  ,  &  $ empno)  ; 

OCIDefineByName ($stmt, "ENAME" , s$ename) ; 

OCIExecute ($stmt) ; 

while  (OCIFetch ( $stmt ) )  { 

echo  "empno $empno ." \n" ; 
echo  "ename $ename ." \n" ; 

} 

OCIFreeStatement ($stmt) ; 

OCILogoff ($conn) ; 

?> 


OCIBindByName  (PHP  3>=  3.0.4,  PHP  4  >=  4.0.0) 


Enlaza  una  variable  PHP  a  un  Placeholder  de  Oracle 
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int  OCIBindByName  (int  stmt,  string  ph_name,  mixed  ^.variable ,  int length  [, 
int  type] ) 


OCIBindByName()  enlaza  la  variable  PHP  variable  a  un  placeholder  de  Oracle  ph_name.  Si  esta 
sera  usada  para  entrada  o  salida  se  determinant  en  tiempo  de  ejecucion,  y  sera  resevado  el  espacio 
necesario  de  almacenamiento.  El  parametro  length  establece  el  tamano  maximo  del  enlace.  Si 
establece  length  a  -1  OCIBindByName()  usara  el  tamano  de  la  variable  para  establecer  el  tamano 
maximo. 

Si  necesita  enlazar  tipos  de  datos  abstractos  (LOB/ROWID/BFILE)  necesitara  primero  reservar  la 
memoria  con  la  funcion  OCINewDescriptor().  length  no  se  usa  para  tipos  de  datos  abstractos  y 
debena  establecerse  a  -1.  La  variable  type  le  informa  a  Oracle,  que  tipo  de  descriptor  queremos  usar. 
Los  valores  posibles  son:  OCI_B_FILE  (Binary-File),  OCI_B_CFILE  (Character-File),  OCI_B_CLOB 
(Character-LOB),  OCI_B_BLOB  (Binary-LOB)  and  OCI_B_ROWID  (ROWID). 

Ejemplo  1.  OCIDefineByName 

<?php 

/*  OCIBindByPos  example  thies@digicol.de  (980221) 

inserts  3  resords  into  emp,  and  uses  the  ROWID  for  updating  the 
records  just  after  the  insert. 

*/ 


$conn  =  OCILogon (" scott ", "tiger ") ; 

$stmt  =  OCIParse  ( $conn, " insert  into  emp  (empno,  ename)  ". 

"values  (: empno,  rename)  ". 

"returning  ROWID  into  rrid"); 

$data  =  array (1111  =>  "Larry",  2222  =>  "Bill",  3333  =>  "Jim"); 

$rowid  =  OCINewDescriptor ($conn, 0CI_D_R0WID) ; 

OCIBindByName ( $stmt , " : empno " , &$ empno, 32 ) ; 

OCIBindByName ( $stmt ,  " : ename " , &$ ename, 32 ) ; 

OCIBindByName ( $stmt ,  " rrid", &$rowid, -1 , 0CI_B_R0WID ) ; 

$update  =  OCIParse ( $conn, "update  emp  set  sal  =  rsal  where  ROWID  =  rrid"); 
OCIBindByName ( $update, "rrid", &$rowid, -1 , 0CI_B_R0WID) ; 

OCIBindByName ( $update, " : sal" , &$sal, 32 ) ; 

$sal  =  10000; 

while  (list ($empno, $ename)  =  each($data))  { 

OCIExecute ( $stmt ) ; 

OCIExecute ($update)  ; 

} 

$rowid->f ree ( )  ; 
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OCIFreeStatement ($update) ; 

OCIFreeStatement ($stmt) ; 

$stmt  =  OCIParse ( $conn, " select  *  from  emp  where  empno  in  (1111,2222,3333)"); 
OCIExecute ($stmt) ; 

while  (OCIFetchlnto ($stmt, &$arr, OCI_ASSOC) )  { 

var_dump ($arr) ; 

} 

OCIFreeStatement ($stmt) ; 

/*  delete  our  "junk"  from  the  emp  table. ...  */ 

$stmt  =  OCIParse ($conn, "delete  from  emp  where  empno  in  (1111,2222,3333)"); 
OCIExecute ($stmt) ; 

OCIFreeStatement ($stmt) ; 

OCILogoff ($conn) ; 

?> 


OCILogon  (PHP  3>=  3.0.4,  PHP  4  >=  4.0.0) 

Establece  la  conexion  con  Oracle 


int  OCILogon  (string  username,  string  password  [,  string  db] ) 


OCILogon()  devuelve  el  identificador  de  conexion  necesario  en  la  mayoria  de  las  funciones  OCI.  El 
tercer  parametro,  que  es  opcional,  puede  contener  el  nombre  de  la  instancia  a  Oracle  o  el  nombre  dado  en 
el  fichero  tnsnames.ora  de  la  base  de  datos  a  la  que  nos  queremos  conectar.  Si  este  parametro  no  se 
especifica,  PHP  usa  la  variable  de  entorno  ORACLE_SID  (Oracle  instance)  o  TWO_TASK 
(tnsnames.ora)  para  determinar  la  base  de  datos  con  la  que  queremos  conectar. 

Las  conexiones  son  compartidas  a  nivel  de  pagina  cuando  usemos  OCILogon().  Lo  cual  significa  que 
los  "commits"  y  "rollbacks"  son  aplicadas  a  todas  las  transacciones  abiertas  en  la  pagina,  incluso  si  usted 
ha  creado  conexiones  multiples. 

Este  ejemplo  demuestra  como  son  compartidas  las  conexiones. 

Ejemplo  1.  OCILogon 

<?php 

print  " <HTMLXPRE>"  ; 

$db  = 

$cl  =  ocilogon (" scott ", "tiger ", $db) ; 

$c2  =  ocilogon (" scott ", "tiger ", $db) ; 

function  create_table ( $conn) 
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{  $stmt  =  ociparse ( $conn, "create  table  scott. hallo  (test  varchar2 ( 64 ) ) " ) ; 
ociexecute ($stmt) ; 
echo  $conn."  created  table\n\n"; 

} 


function  drop_table ($conn) 

{  $stmt  =  ociparse ( $conn, "drop  table  scott . hallo" ) ; 
ociexecute ($stmt) ; 
echo  $conn."  dropped  table\n\n"; 

} 

function  insert_data ( $conn) 

{  $stmt  =  ociparse ( $conn, " insert  into  scott. hallo 

values  (' $conn'  II  '  '  II  to_char (sysdate, ' DD-MON-YY  HH24 :MI : SS' ) ) " ) 

ociexecute ($stmt, OCI_DEFAULT) ; 
echo  $conn."  inserted  hallo\n\n"; 

} 

function  delete_data ( $conn) 

{  $stmt  =  ociparse  ( $conn, "delete  from  scott . hallo" ) ; 
ociexecute ($stmt, OCI_DEFAULT) ; 
echo  $conn."  deleted  hallo\n\n"; 

} 

function  commit ($conn) 

{  ocicommit ( $conn) ; 

echo  $conn."  commited\n\n" ; 

} 

function  rollback  ($conn) 

{  ocirollback ( $conn) ; 

echo  $conn."  rollback\n\n" ; 

} 


function  select_data ($conn) 

{  $stmt  =  ociparse ( $conn, " select  *  from  scott .hallo")  ; 
ociexecute ($stmt, OCI_DEFAULT) ; 

echo  $conn." - selecting\n\n" ; 

while  (ocifetch ($stmt) ) 

echo  $conn."  <" . ociresult ( $stmt , "TEST" ) . ">\n\n" ; 
echo  $conn." - done\n\n"; 


create_table ( $  cl ) ; 

insert_data ( $cl ) ; 

// 

Insert 

insert_data ($c2) ; 

// 

Insert 

select_data ($cl) ; 

// 

Results 

select_data ($c2) ; 

a  row  using  cl 
a  row  using  c2 

of  both  inserts  are  returned 


rollback  ( $ c 1 ) ; 


/ /  Rollback  using  cl 


select_data ( $cl ) ; 


//  Both  inserts  have  been  rolled  back 
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select_data ($c2) ; 

insert_data ($c2) ; 

// 

Insert 

a  row  using 

c2 

commit ( $c2 ) ; 

// 

commit 

using  c2 

select_data ( $cl ) ; 

// 

result 

of  c2  insert 

is  returned 

delete_data ( $cl ) ; 

// 

delete 

all  rows  in 

table  using  cl 

select_data ( $cl ) ; 

// 

no  rows 

returned 

select_data ($c2) ; 

// 

no  rows 

returned 

commit ( $cl ) ; 

// 

commit 

using  cl 

select_data ( $cl ) ; 

// 

no  rows 

returned 

select_data ($c2) ; 

// 

no  rows 

returned 

drop_table ( $  cl ) ; 
print  "</PREx/HTML>"; 
?> 


See  also  OCIPLogon()  and  OCINLogonQ. 


OCIPLogon  (PHP  3>=  3.0.8,  PHP  4  >=  4.0.0) 

Conecta  con  una  base  de  datos  Oracle  usando  una  conexion  persistente.  Devuelve  una  nueva  sesion. 

int  OCIPLogon  (string  username,  string  password  [,  string  db] ) 


OCIPLogonO  crea  una  conexion  persistente  con  una  base  de  datos  Oracle  8.  El  tercer  parametro,  que  es 
opcional,  puede  contener  el  nombre  de  la  instancia  a  Oracle  o  el  nombre  dado  en  el  fichero  tnsnames.ora 
de  la  base  de  datos  a  la  que  nos  queremos  conectar.  Si  este  parametro  no  se  especifica,  PHP  usa  la 
variable  de  entorno  ORACLE_SID  (Oracle  instance)  o  TWO_TASK  (tnsnames.ora)  para  determinar  la 
base  de  datos  con  la  que  queremos  conectar. 

Vea  tambien  OCILogonQ  y  OCINLogonQ. 


OCINLogon  (PHP  3>=  3.0.8,  PHP  4  >=  4.0.0) 

Conecta  con  una  base  de  datos  Oracle  usando  una  nueva  conexion.  Devuelve  una  nueva  sesion. 


int  OCINLogon  (string  username,  string  password  [,  string  db] ) 
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OCINLogon()  crea  una  nueva  conexion  con  una  base  de  datos  Oracle  8.  El  tercer  parametro,  que  es 
opcional,  puede  contener  el  nombre  de  la  instancia  a  Oracle  o  el  nombre  dado  en  el  fichero  tnsnames.ora 
de  la  base  de  datos  a  la  que  nos  queremos  conectar.  Si  este  parametro  no  se  especifica,  PHP  usa  la 
variable  de  entorno  ORACLE_SID  (Oracle  instance)  o  TWO_TASK  (tnsnames.ora)  para  determinar  la 
base  de  datos  con  la  que  queremos  conectar. 

OCINLogon()  fuerza  una  nueva  conexion.  Se  debe  usar  si  necesita  aislar  un  conjunto  de  transacciones. 
Por  defecto,  las  conexiones  son  compartidas  a  nivel  de  pagina  si  usa  OCILogon()  o  a  nivel  del  proceso 
del  servidor  web  si  usa  OCIPLogon().  Si  posee  multiples  conexiones  abiertas  usando  OCINLogon(), 
todos  los  "commits"  y  "rollbacks"  se  aplican  solo  a  la  conexion  especificada. 

Este  ejemplo  demuestra  como  las  conexiones  estan  separadas. 

Ejemplo  1.  OCINLogon 


<?php 

print  " <HTMLXPRE> "  ; 

$db  = 

$cl  =  ocilogon (" scott ", "tiger ", $db) ; 

$c2  =  ocinlogon (" scott ", "tiger ", $db) ; 

function  create_table ( $conn) 

{  $stmt  =  ociparse ( $conn, "create  table  scott. hallo  (test 
varchar2  (  64 ) )  "  ) ; 

ociexecute ($stmt) ; 

echo  $conn."  created  table\n\n"; 

} 

function  drop_table ($conn) 

{  $stmt  =  ociparse ( $conn, "drop  table  scott . hallo" ) ; 
ociexecute ($stmt) ; 
echo  $conn."  dropped  table\n\n"; 

} 

function  insert_data ($conn) 

{  $stmt  =  ociparse ( $conn, " insert  into  scott. hallo 

values (' $conn'  II  '  '  II  to_char (sysdate, ' DD-MON-YY  HH24 :MI : SS' ) ) " ) 

ociexecute ($stmt, OCI_DEFAULT) ; 
echo  $conn."  inserted  hallo\n\n"; 

} 

function  delete_data ($conn) 

{  $stmt  =  ociparse ( $conn, "delete  from  scott .hallo" ) ; 
ociexecute ($stmt, OCI_DEFAULT) ; 
echo  $conn."  deleted  hallo\n\n"; 

} 

function  commit ($conn) 

{  ocicommit ( $conn) ; 

echo  $conn."  commited\n\n" ; 

} 

function  rollback ($conn) 
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{  ocirollback ( $conn) ; 

echo  $conn."  rollback\n\n" ; 

} 

function  select_data ( $conn) 

{  $stmt  =  ociparse ( $conn, " select  *  from  scott . hallo" ) ; 
ociexecute ($stmt, OCI_DEFAULT) ; 

echo  $conn." - selecting\n\n" ; 

while  (ocifetch ($stmt) ) 

echo  $conn."  <" . ociresult ($stmt, "TEST" ) . ">\n\n" ; 
echo  $conn." - done\n\n"; 

} 

create_table ( $  cl ) ; 
insert_data ( $cl ) ; 

select_data ( $cl ) ; 
select_data ($c2) ; 

rollback  ( $cl ) ; 

select_data ( $cl ) ; 
select_data ($c2) ; 

insert_data ($c2) ; 
commit ( $c2 ) ; 

select_data ( $cl ) ; 

delete_data ( $cl ) ; 
select_data ( $cl ) ; 
select_data ($c2) ; 
commit ( $cl ) ; 

select_data ( $cl ) ; 
select_data ($c2) ; 


drop_table ( $  cl ) ; 
print  "</PREx/HTML>" ; 
?> 


See  also  OCILogon()  and  OCIPLogon(). 


OCILogOff  (PHP 


3>=  3.0.4,  PHP  4  >=  4.0.0) 


Termina  la  conexion  con  Oracle 
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int  OCILogOff  (int  connection) 


OCILogOffQ  cierra  una  conexion  con  Oracle. 


OClExecute  (PHP  3>=  3.0.4,  PHP  4  >=  4.0.0) 

Ejecuta  una  sentencia 

int  OClExecute  (int  statement  [,  int  mode]) 


OCIExecute()  ejecuta  una  sentencia  previamente  analizada.  (see  OCIParseO).  El  parametro  opcional 
mode  le  permite  especificar  el  modo  de  ejecucion  (default  is  OCI_COMMIT_ON_SUCCESS).  Si  no 
desea  que  las  sentencias  se  confirmen  automaticamente,  especifique  OCI_DEFAULT  como  su  modo. 


OCICommit  (PHP  3>=  3.0.7,  PHP  4  >=  4.0.0) 

Confirma  transacciones  pendientes 

int  OCICommit  (int  connection) 


OCICommitO  confirma  todas  las  sentencias  pendientes  para  la  conexion  con  Oracle  connection. 


OCIRollback  (PHP  3>=  3.0.7,  PHP  4  >=  4.0.0) 

Restablece  todas  las  transaciones  sin  confirmar 

int  OCIRollback  (int  connection) 


OCIRollback()  restablece  todas  las  transacciones  sin  confirmar  para  la  conexion  Oracle  connection. 


OCINewDescriptor  (PHP  3>=  3.0.7,  PHP  4  >=  4.0.0) 

Inicializa  un  nuevo  descriptor  vacfo  LOB/FILE  (LOB  por  defecto) 
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string  OCINewDescriptor  (int  connection  [,  int  type]) 


OCINewDescriptor()  Reserva  espacio  para  mantener  descriptores  o  localizadores  LOB.  Los  valores 
validos  para  el  tipo  type  son  OCI_D_FILE,  OCI_D_LOB,  OCI_D_ROWID.  Para  descriptores  LOB, 
los  metodos  load,  save,  y  savefile  estan  asociados  con  el  descriptor,  para  BFILE  solo  el  metodo  load 
existe.  Vea  el  segundo  ejemplo. 

Ejemplo  1.  OCINewDescriptor 

<?php 

/*  This  script  is  designed  to  be  called  from  a  HTML  form. 

*  It  expects  $user,  $password,  Stable,  $where,  and  $commitsize 

*  to  be  passed  in  from  the  form.  The  script  then  deletes 

*  the  selected  rows  using  the  ROWID  and  commits  after  each 

*  set  of  Scommitsize  rows.  (Use  with  care,  there  is  no  rollback) 

*/ 

$conn  =  OCILogon  ( $user ,  $password) ; 

$stmt  =  OCIParse ( $conn, " select  rowid  from  Stable  Swhere"); 

Srowid  =  OCINewDescriptor ( $conn, OCI_D_ROWID ) ; 

OCIDef ineByName ($stmt, "ROWID" , &$rowid) ; 

OCIExecute ( $stmt ) ; 

while  (  OCIFetch ($stmt)  )  { 

$nrows  =  OCIRowCount ( $stmt ) ; 

Sdelete  =  OCIParse ($conn, "delete  from  Stable  where  ROWID  =  :rid"); 
OCIBindByName ( $ delete, " : rid" , &$ rowid, -1 , OCI_B_ROWID) ; 

OCIExecute (Sdelete) ; 
print  "$nrows\n"; 

if  (  (Snrows  %  Scommitsize)  ==  0  )  { 

OCICommit (Sconn) ; 

} 

} 

Snrows  =  OCIRowCount ( Sstmt ) ; 
print  "Snrows  deleted  ... \n" ; 

OCIFreeStatement (Sstmt) ; 

OCILogoff (Sconn) ; 

?> 

<?php 

/*  This  script  demonstrates  file  upload  to  LOB  columns 

*  The  formfield  used  for  this  example  looks  like  this 

*  <form  action="upload.php3"  method="post "  enctype="multipart/form-data"> 

*  <input  type="file"  name="lob_upload"> 

* 

*/ 

if ( ! isset ($lob_upload)  | |  $lob_upload  ==  'none' ) { 

?> 

<form  action="upload.php3"  method="post "  enctype="multipart/form-data"> 

Upload  file:  <input  type="file"  name="lob_upload"><br> 

<input  type=" submit "  value="Upload">  -  cinput  type="reset "> 

</ f orm> 

<?php 
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}  else  { 

//  $lob_upload  contains  the  temporary  filename  of  the  uploaded  file 
$conn  =  OCILogon ( $user,  $password) ; 

$lob  =  OCINewDescriptor ( $conn,  OCI_D_LOB) ; 

$stmt  =  OCIParse ( $conn, " insert  into  $table  (id,  the_blob) 

values (my_seq . NEXTVAL,  EMPTY_BLOB ( ) )  returning  the_blob  into  :the_blob") 
OCIBindByName ( $stmt ,  ':the_blob',  &$lob,  -1,  OCI_B_BLOB) ; 

OCIExecute ($stmt) ; 

if ( $lob->savef ile ( $lob_upload) ) { 

OCICommit ($conn) ; 

echo  "Blob  successfully  uploaded\n"; 

} else { 

echo  "Couldn't  upload  Blob\n"; 

} 

OCIFreeDescriptor ($lob) ; 

OCIFreeStatement ($stmt) ; 

OCILogoff ($conn) ; 

} 

?> 


OCIRowCount  (PHP  3>=  3.0.7,  PHP  4  >=  4.0.0) 

Obtiene  el  numero  de  filas  afectadas 


int  OCIRowCount  (int  statement) 


OCIRowCountO  devuelve  el  numero  de  filas  afectadas,  por  ej.  en  sentencias  de  actualization.  !Esta 
funcion  no  indicara  el  numero  de  de  filas  que  devuelve  una  sentencia  SELECT! 


Ejemplo  1.  OCIRowCount 

<?php 

print  " <HTMLXPRE> "  ; 

$conn  =  OCILogon (" scott ", "tiger ") ; 

$stmt  =  OCIParse ( $conn, "create  table  emp2  as  select  *  from  emp"); 
OCIExecute ( $stmt ) ; 

print  OCIRowCount ($stmt)  .  "  rows  inserted . <BR>" ; 

OCIFreeStatement ($stmt) ; 

$stmt  =  OCIParse ($conn, "delete  from  emp2"); 

OCIExecute ( $stmt ) ; 

print  OCIRowCount ($stmt)  .  "  rows  deleted. <BR>" ; 

OCICommit ($conn) ; 

OCIFreeStatement ($stmt) ; 

$stmt  =  OCIParse ($conn, "drop  table  emp2"); 

OCIExecute ( $stmt ) ; 

OCIFreeStatement ($stmt) ; 
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?> 


OCINumCols  (PHP  3>=  3.0.4,  PHP  4  >=  4.0.0) 

Devuelve  el  numero  de  columnas  resultantes  en  una  sentencia 


int  OCINumCols  (int  stmt) 


OCINumColsO  devuelve  el  numero  de  columnas  en  una  sentencia 

Ejemplo  1.  OCINumCols 

<?php 

print  "<HTMLXPRE>\n" ; 

$conn  =  OCILogon (" scott " ,  "tiger"); 

$stmt  =  OCIParse ( $conn, " select  *  from  emp"); 

OCIExecute ( $stmt ) ; 
while  (  OCIFetch ( $stmt )  )  { 

print  "\n"; 

$ncols  =  OCINumCols ( $stmt ) ; 

for  (  $i  =  1;  $i  <=  $ncols;  $i++  )  { 

$column_name  =  OCIColumnName ( $stmt , $i ) ; 

$coluran_value  =  OCIResult ($stmt, $i) ; 

print  $column_name  .  '  :  '  $column_value  .  "\n"; 

} 

print  "\n"; 

} 

OCIFreeStatement ($stmt) ; 

OCILogoff ($conn) ; 
print  " </PRE> " ; 
print  "</HTML>\n" ; 


OCIResult  (PHP  3>=  3.0.4,  PHP  4  >=  4.0.0) 

Devuelve  el  valor  de  una  columna  en  la  fila  buscada 


mixed  OCIResult  (int  statement ,  mixed  column) 
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OCIResult()  devuelve  el  valor  de  la  columna  column  de  la  fila  actual  (vea  OCIFetch()).OCIResult() 
devolvera  todo  como  una  cadena  excepto  para  los  tipo  de  datos  abstractos  (ROWIDs,  LOBs  and  FILEs). 


OCIFetch  (PHP  3>=  3.0.4,  PHP  4  >=  4.0.0) 
Busca  la  siguiente  fila  en  el  result-buffer 

int  OCIFetch  (int  statement) 


OCIFetchQ  Busca  la  siguiente  fila  (para  sentencias  SELECT)  dentro  del  result-buffer  interno. 


OCIFetchlnto  (PHP  3>=  3.0.4,  PHP  4  >=  4.0.0) 

Busca  la  siguiente  fila  dentro  del  result-array 

int  OCIFetchlnto  (int  stmt,  array  &result  [,  int  mode]) 


OCIFetchInto()  busca  la  siguiente  fila  (for  SELECT  statements)  dentro  del  array  result. 
OCIFetchInto()  sobreescribira  el  contenido  previo  de  result.  Por  defecto  result  contendra  un 
array  basado  en  todas  las  columnas  que  no  son  null. 

El  parametro  mode  le  permite  cambiar  el  comportamineto  por  defecto.  Puede  especificar  mas  de  una  flag 
simplemente  anadiendolas  (ej.  OCI_ASSOC+OCI_RETURN_NULLS).  Las  flags  son: 

OCi_ASSOC  Devuelve  un  array  asociativo. 

OCI_num  Devuelve  un  array  numerado  empezando  en  1.  (POR  DEFECTO) 

OCI_RETURN_nulls  Devuelve  columnas  vacias. 

OCI_RETURN_lobs  Devuelve  el  valor  de  un  LOB  en  vez  de  el  descriptor. 


OCIFetchStatement  (PHP  3>=  3.0.8,  PHP  4  >=  4.0.0) 

Busca  todas  la  filas  de  un  resultset  dentro  de  un  array. 

int  OCIFetchStatement  (int  stmt,  array  & variable ) 
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OCIFetchStatementO  busca  todas  las  filas  de  un  resultset  dentro  de  un  array  definido  por  el  usuario. 
OCIFetchStatement()  devuelve  el  numero  de  filas  buscadas. 

Ejemplo  1.  OCIFetchStatement 

<?php 

/*  OCIFetchStatement  example  mbritton@verinet.com  (990624)  */ 

$conn  =  OCILogon (" scott ", "tiger ") ; 

$stmt  =  OCIParse ( $conn, " select  *  from  emp"); 

OCIExecute ($stmt) ; 

$nrows  =  OCIFetchStatement ($stmt, $results) ; 
if  (  $nrows  >  0  )  { 

print  " <TABLE  BORDER=\ " 1 \ " >\n " ; 
print  "<TR>\n" ; 

while  (  list  (  $key,  $val  )  =  each  (  Sresults  )  )  { 

print  "<TH>$key</TH>\n" ; 

} 

print  "</TR>\n" ; 

for  (  $i  =  0;  $i  <  $nrows;  $i++  )  { 

reset (Sresults) ; 
print  "<TR>\n" ; 

while  (  $column  =  each ( $results )  )  { 

$data  =  $column [' value' ] ; 
print  "<TD>$data [ $ i ] </TD>\n"; 

} 

print  "</TR>\n" ; 

1 

print  "</TABLE>\n" ; 

}  else  { 

echo  "No  data  found<BR>\n" ; 

} 

print  "$nrows  Records  Selected<BR>\n" ; 

OCIFreeStatement ($stmt) ; 

OCILogoff ($conn) ; 

?> 


OCIColumnlsNULL  (PHP  3>=  3.0.4,  PHP  4  >=  4.0.0) 

comprueba  si  una  una  columna  es  null 

int  OCIColumnlsNULL  (int  stmt,  mixed  column) 
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OCIColumnSize  (PHP  3>=  3.0.4,  PHP  4  >=  4.0.0) 

devuelve  el  tamano  de  la  columna 


int  OCIColumnSize  (int  stmt,  mixed  column) 


OCIColumnSizeO  devuelve  el  tamano  de  la  columna  indicada  por  Oracle  Puede  utilizar  el  numero  de  la 
columna  (1-Based)  o  el  nombre  indicado  en  el  parametro  col. 


Ejemplo  1.  OCIColumnSize 

<?php 

print  "<HTMLXPRE>\n" ; 

$conn  =  OCILogon (" scott " ,  "tiger"); 

$stmt  =  OCIParse ( $conn, " select  *  from  emp"); 

OCIExecute ( $stmt ) ; 

print  " <TABLE  BORDER=\ " 1 \ " > " ; 

print  " <TR> " ; 

print  "<TH>Name</TH>" ; 

print  "<TH>Type</TH>" ; 

print  "<TH>Length</TH>" ; 

print  "</TR>" ; 

$ncols  =  OCINumCols ($stmt) ; 

for  (  $i  =  1;  $i  <=  $ncols;  $i++  )  { 

$column_name  =  OCIColumnName ( $stmt , $i ) ; 
$column_type  =  OCIColumnType ( $stmt , $i ) ; 
$column_size  =  OCIColumnSize ( $stmt, $i ) ; 
print  " <TR> " ; 

print  "<TD>$column_name</TD>" ; 
print  "<TD>$column_type</TD>" ; 
print  "<TD>$column_size</TD>" ; 
print  " </ TR> " ; 

} 

print  "</TABLE>" ; 

OCIFreeStatement ($stmt) ; 

OCILogoff ($conn) ; 
print  " </PRE> " ; 
print  "</HTML>\n"; 
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Vea  tambien  OCINumColsQ,  OCIColumnName(),  y  OCIColumnSize(). 


OCIServerVersion  (PHP  3>=  3.0.4,  PHP  4  >=  4.0.0) 


Devuelve  una  cadena  conteniendo  informacion  a  cerca  de  la  version  del  servidor. 


string  OCIServerVersion  (int  conn ) 


Ejemplo  1.  OCIServerVersion 

<?php 

$conn  =  OCILogon ( "scott" , "tiger" ) ; 

print  "Server  Version:  "  .  OCIServerVersion ($conn) ; 

OCILogOff  ($conn) ; 

?> 


OCIStatementType  php  3>=  3.0.5,  php  4  >=  4.0.0 


Devuelve  el  tipo  de  una  sentencia  OCI. 


string  OCIStatementType  (int  stmt) 


OCIStatementTypeO  devuelve  uno  de  los  siguiente  valores: 

1.  "SELECT" 

2.  "UPDATE" 

3.  "DELETE" 

4.  "INSERT" 

5.  "CREATE" 

6.  "DROP" 

7.  "ALTER" 

8.  "BEGIN" 

9.  "DECLARE" 

10.  "UNKNOWN" 
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Ejemplo  1.  Code  examples 

<?php 

print  " <HTMLXPRE> "  ; 

$conn  =  OCILogon (" scott ", "tiger ") ; 

$sql  =  "delete  from  emp  where  deptno  =  10"; 

$stmt  =  OCIParse ( $conn,  $sql )  ; 

if  (  OCIStatementType ($stmt)  ==  "DELETE"  )  { 

die  "You  are  not  allowed  to  delete  from  this  table<BR>"; 

} 

OCILogoff ($conn) ; 
print  "</PRE></HTML>" ; 

?> 


OCINewCursor  (PHP  3>=  3.0.8,  PHP  4  >=  4.0.0) 

devuelve  un  cursor  nuevo  (Statement-Handle)  -  use  esto  para  enlazar  ref-cursors! 

int  OCINewCursor  (int  conn) 


OCINewCursorQ  allocates  a  new  statement  handle  on  the  specified  connection. 


Ejemplo  1.  Usando  un  REF  CURSOR  de  un  procedimiento  almacenado 

<?php 

//  suppose  your  stored  procedure  info. output  returns  a  ref  cursor  in  :data 

$conn  =  OCILogon (" scott ", "tiger ") ; 

$curs  =  OCINewCursor ($conn) ; 

$stmt  =  OCIParse ( $conn, "begin  inf o . output (: data) ;  end;"); 

ocibindbyname ( $stmt , "data" , &$curs, -1 , OCI_B_CURSOR) ; 
ociexecute ($stmt) ; 
ociexecute ($curs) ; 

while  (OCIFetchlnto ( $curs , & $data) )  { 

var_dump ($data) ; 

} 

OCIFreeCursor ($stmt) ; 
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?> 
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Ejemplo  2.  Usando  un  REF  CURSOR  en  una  sentencia  select 

<?php 

print  "  <HTMLXBODY>  "  ; 

$conn  =  OCILogon (" scott ", "tiger ") ; 

$count_cursor  =  "CURSOR (select  count (empno)  num_emps  from  emp  "  . 

"where  emp.deptno  =  dept.deptno)  as  EMPCNT  from  dept"; 
$stmt  =  OCIParse  ( $conn, " select  deptno, dname, $count_cursor " ) ; 

ociexecute ($stmt) ; 

print  " <TABLE  BORDER= \ " 1 \ ; 

print  " <TR> " ; 

print  " <TH>DEPT  NAME</TH>" ; 
print  " <TH>DEPT  #</TH>"; 
print  "<TH>#  EMPLOYEES</TH> " ; 
print  "</TR>" ; 

while  (OCIFetchlnto ($stmt, &$data, OCI_ASSOC) )  { 

print  " <TR> " ; 

$dname  =  $data [ "DNAME" ] ; 

Sdeptno  =  $data [ "DEPTNO" ] ; 
print  "<TD>$dname</TD>" ; 
print  "<TD>$deptno</TD>" ; 
ociexecute ( $data [  "EMPCNT"  ]); 

while  (OCIFetchlnto ($data [  "EMPCNT"  ]  , &$subdata, OCI_ASSOC) )  { 

$num_emps  =  $subdata [ "NUM_EMPS " ] ; 
print  "<TD>$num_emps</TD>" ; 

} 

print  "</TR>" ; 

} 

print  "</TABLE>" ; 
print  "</BODYx/HTML>"  ; 

OCIFreeStatement ($stmt) ; 

OCILogoff ($conn) ; 

?> 


OCIFreeStatement  (PHP  3>=  3.0.5,  PHP  4  >=  4.0.0) 


Libera  todos  los  recursos  asociados  con  una  sentencia. 
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int  OCIFreeStatement  (int  stmt) 


OCIFreeStatementO  devuelve  cierto  si  la  operacion  se  lleva  a  cabo,  o  falso  en  caso  contrario. 


OCIFreeCursor  (PHP  3>=  3.0.8,  PHP  4  >=  4.0.0) 

Libera  todos  los  recursos  asociados  con  cursor. 


int  OCIFreeCursor  (int  stmt) 


OCIFreeCursor ()  devuelve  cierto  si  la  operacion  se  lleva  a  cabo,  o  falso  en  caso  contrario. 


OCIColumnName  (PHP  3>=  3.0.4,  PHP  4  >=  4.0.0) 


Devuelve  el  nombre  de  una  columna. 


string  OCIColumnName  (int  stmt,  int  col) 


OCIColumnNameO  Devuelve  el  nombre  de  la  columna  correspondiente  al  numero  de  la  columna 
(1 -based)  que  es  pasado. 


Ejemplo  1.  OCIColumnName 

<?php 

print  "<HTMLXPRE>\n" ; 

$conn  =  OCILogon (" scott " ,  "tiger"); 

$stmt  =  OCIParse ( $conn, " select  *  from  emp"); 

OCIExecute ( $stmt ) ; 

print  " <TABLE  B0RDER=\ " 1 \ " > " ; 

print  " <TR> " ; 

print  "<TH>Name</TH>" ; 

print  "<TH>Type</TH>" ; 

print  "<TH>Length</TH>" ; 

print  "</TR>" ; 

$ncols  =  OCINumCols ($stmt) ; 

for  (  $i  =  1;  $i  <=  $ncols;  $i++  )  { 

$coluran_name  =  OCIColumnName ($stmt, $i) ; 
$column_type  =  OCIColumnType ( $stmt , $i ) ; 
$column_size  =  OCIColumnSize ( $stmt , $i ) ; 
print  " <TR> " ; 
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print  "<TD>$column_name</TD>" ; 
print  "<TD>$column_type</TD>" ; 
print  "<TD>$column_size</TD>" ; 
print  " </TR> " ; 

} 

OCIFreeStatement ($stmt) ; 

OCILogoff ($conn) ; 
print  " </PRE> " ; 
print  "</HTML>\n" ; 


Vea  tambien  OCINumColsQ,  OCIColumnTypeQ,  y  OCIColumnSize(). 


OCIColumnType  (PHP  3>=  3.0.4,  PHP  4  >=  4.0.0) 


Devuelve  el  tipo  de  dato  de  una  columna. 


mixed  OCIColumnType  (int  stmt ,  int  col) 


OCIColumnTypeO  devuelve  el  tipo  de  dato  de  una  columna  correspondiente  al  numero  de  la  columna 
(1-based)  que  es  pasado. 


Ejemplo  1.  OCIColumnType 

<?php 

print  "<HTMLXPRE>\n" ; 

$conn  =  OCILogon (" scott " ,  "tiger"); 

$stmt  =  OCIParse ( $conn, " select  *  from  emp"); 

OCIExecute ( $stmt ) ; 

print  " <TABLE  B0RDER=\ " 1 \ " > " ; 

print  " <TR> " ; 

print  "<TH>Name</TH>" ; 

print  "<TH>Type</TH>" ; 

print  "<TH>Length</TH>" ; 

print  "</TR>" ; 

$ncols  =  OCINumCols ($stmt) ; 

for  (  $i  =  1;  $i  <=  $ncols;  $i++  )  { 

$column_name  =  OCIColumnName ( $stmt , $i ) ; 
$column_type  =  OCIColumnType ( $stmt, $i ) ; 
$column_size  =  OCIColumnSize ( $stmt , $i ) ; 
print  " <TR> " ; 

print  "<TD>$column_name</TD>" ; 
print  "<TD>$column_type</TD>" ; 
print  "<TD>$column_size</TD>" ; 
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print  "</TR>" ; 

} 

OCIFreeStatement ($stmt) ; 
OCILogoff  ($conn) ; 
print  "</PRE>" ; 
print  "</HTML>\n"; 


Vea  tambien  OCINumCols(),  OCIColumnName(),  y  OCIColumnSize(). 


OCIParse  (PHP  3>=  3.0.4,  PHP  4  >=  4.0.0) 

Analiza  una  consulta  y  devuelve  una  sentencia 

int  OCIParse  (int  conn,  strint  query) 


OCIParseO  analiza  la  query  usando  conn.  Devuelve  el  identificador  de  la  sentencia  si  la  consulta  es 
valida,  y  falso  si  no  lo  es.  La  query  puede  ser  cualquier  sentencia  SQL  valida. 


OCIError  (PHP  3>=  3.0.7,  PHP  4  >=  4.0.0) 

Devuelve  el  ultimo  error  de  stmtlconnlglobal.  Si  no  ocurre  ningun  error  devuelve  falso. 

array  OCIError  ([int  stmtlconnlglobal]) 


OCIError()  devuelve  el  ultimo  error  encontrado.  Si  el  parametro  opcional  stmt  /  conn  /  global  no  es 
usado,  es  devuelto  el  ultimo  error  encontrado.  Si  no  se  encuentra  ningun  error,  OCIError()  devuelve 
falso.  OCIError()  devuelve  el  error  como  un  array  asociativo.  En  este  array,  code  consiste  en  el  codigo 
de  error  de  Oracle  y  message  en  la  cadena  de  description  del  error. 


OCIInternalDebug  (PHP  3>=  3.0.4,  PHP  4  >=  4.0.0) 

Habilita  o  deshabilita  la  salida  del  depurador  interno.  Por  defecto  este  esta  deshabiltado 

void  OCIInternalDebug  (int  onoff) 
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OCIIntemalDebugO  habilita  la  salida  del  depurador  interno.  Asigne  0  a  onoff  para  deshabilitar  la 
salida  y  1  para  habilitarla. 
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LIX.  OpenSSL  functions 


Aviso 

This  module  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  these 
functions,  these  function  names,  in  concreto  ANYTHING  documented  here  can 
change  in  a  future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this 
module  at  your  own  risk. 


Introduction 


This  module  uses  the  functions  of  OpenSSL  (http://www.openssl.org/)  for  generation  and  verification  of 
signatures  and  for  sealing  (encrypting)  and  opening  (decrypting)  data.  PHP-4.0.4pll  requires  OpenSSL 
>=  0.9.6,  but  PHP-4.0.5  and  greater  with  also  work  with  OpenSSL  >=  0.9.5. 

Nota:  Please  keep  in  mind  that  this  extension  is  still  considered  experimental! 


OpenSSL  offers  many  features  that  this  module  currently  doesn’t  support.  Some  of  these  may  be  added 
in  the  future. 


Key/Certificate  parameters 

Quite  a  few  of  the  openssl  functions  require  a  key  or  a  certificate  parameter.  PHP  4.0.5  and  earlier  have 
to  use  a  key  or  certificate  resource  returned  by  one  of  the  openssl_get_xxx  functions.  Later  versions  may 
use  one  of  the  following  methods: 


•  Certificates 


1.  An  X.509  resource  returned  from  opens sl_x509_read 

2.  A  string  having  the  format  file :  //path/to/cert  .pern;  the  named  file  must  contain  a  PEM 
encoded  certificate 

3.  A  string  containing  the  content  of  a  certificate,  PEM  encoded 
•  Public/Private  Keys 

1.  A  key  resource  returned  from  openssl_get_publickcy ')  or  openss l_get_pri vatekev ') 

2.  For  public  keys  only:  an  X.509  resource 

3.  A  string  having  the  format  file :  //path/to/file  .pern  -  the  named  file  must  contain  a  PEM 
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encoded  certificate/private  key  (it  may  contain  both) 

4.  A  string  containing  the  content  of  a  certificate/key,  PEM  encoded 

5.  For  private  keys,  you  may  also  use  the  syntax  array ($key,  $passphrase)  where  $key  represents  a 
key  specified  using  the  file://  or  textual  content  notation  above,  and  $passphrase  represents  a 
string  containing  the  passphrase  for  that  private  key 


Certificate  Verification 


When  calling  a  function  that  will  verify  a  signature/certificate,  the  cainfo  parameter  is  an  array 
containing  file  and  directory  names  the  specify  the  locations  of  trusted  CA  files.  If  a  directory  is 
specified,  then  it  must  be  a  correctly  formed  hashed  directory  as  the  openssl  command  would  use. 


PKCS7  Flags/Constants 

The  S/MIME  functions  make  use  of  flags  which  are  specified  using  a  bitfield  which  can  include  one  or 
more  of  the  following  values: 


Tabla  1.  PKCS7  CONSTANTS 


Constant 

Description 

PKCS7_TEXT 

adds  text/plain  content  type  headers  to 
encrypted/signed  message.  If  decrypting  or 
verifying,  it  strips  those  headers  from  the  output  -  if 
the  decrypted  or  verified  message  is  not  of  MIME 
type  text/plain  then  an  error  will  occur. 

PKCS7_BINARY 

normally  the  input  message  is  converted  to 
"canonical"  format  which  is  effectively  using  CR 
and  LF  as  end  of  line:  as  required  by  the  S/MIME 
specification.  When  this  options  is  present,  no 
translation  occurs.  This  is  useful  when  handling 
binary  data  which  may  not  be  in  MIME  format. 

PKCS7_NOINTERN 

when  verifying  a  message,  certificates  (if  any) 
included  in  the  message  are  normally  searched  for 
the  signing  certificate.  With  this  option  only  the 
certificates  specified  in  the  extracerts 
parameter  of  opcnssl_pkcs7_verify ' )  are  used.  The 
supplied  certificates  can  still  be  used  as  untrusted 
CAs  however. 

PKCS7_NOVERIFY 

do  not  verify  the  signers  certificate  of  a  signed 
message. 
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Constant 

Description 

PKCS7_NOCHAIN 

do  not  chain  verification  of  signers  certificates:  that 
is  don’t  use  the  certificates  in  the  signed  message  as 
un trusted  CAs. 

PKCS7_NOCERTS 

when  signing  a  message  the  signer’s  certificate  is 
normally  included  -  with  this  option  it  is  excluded. 
This  will  reduce  the  size  of  the  signed  message  but 
the  verifier  must  have  a  copy  of  the  signers 
certificate  available  locally  (passed  using  the 
extracerts  to  openssl_pkcs7_verify0  for 
example. 

PKCS7_NOATTR 

normally  when  a  message  is  signed,  a  set  of 
attributes  are  included  which  include  the  signing 
time  and  the  supported  symmetric  algorithms.  With 
this  option  they  are  not  included. 

PKCS7_DETACHED 

When  signing  a  message,  use  cleartext  signing  with 
the  MIME  type  multipart/signed.  This  is  the  default 
if  the  flags  parameter  to  openssl_pkcs7_sign ')  if 
you  do  not  specify  any  flags.  If  you  turn  this  option 
off,  the  message  will  be  signed  using  opaque 
signing,  which  is  more  resistant  to  translation  by 
mail  relays  but  cannot  be  read  by  mail  agents  that  do 
not  support  S/MIME. 

PKCS7_NOSIGS 

Don’t  try  and  verify  the  signatures  on  a  message 

Nota:  These  constants  were  added  in  4.0.6. 
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openssl_error_string  (php  4  >=  4.0.6) 


Return  openSSL  error  message 


mixed  openssl_error_string  () 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


Returns  an  error  message  string,  or  false  if  there  are  no  more  error  messages  to  return. 

openssl_error_string()  returns  the  last  error  from  the  openSSL  library.  Error  messages  are  stacked,  so 
this  function  should  be  called  multiple  times  to  collect  all  of  the  information. 

The  parameters/return  type  of  this  function  may  change  before  it  appears  in  a  release  version  of  PHP 


Ejemplo  1.  openssl_error_string()  example 

//  lets  assume  you  just  called  an  openssl  function  that  failed 
while ($msg  =  openssl_error_string) 
echo  $msg  .  "<br>"; 


Nota:  This  function  was  added  in  4.0.6. 


openssl_f  ree_key  (php  4  >=  4  o  4) 


Free  key  resource 


void  openssl_free_key  (resource  key_identifier) 
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Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


openssl_free_key()  frees  the  key  associated  with  the  specified  key_i dent i  fie r  from  memory. 


openssl_get_pri  vatekey  (php  4  >=  4.o.4) 


Prepare  a  PEM  formatted  private  key  for  use 


resource  opens sl_get_privatekey  (mixed  key  [,  string  passphrase ]) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


Returns  a  positive  key  resource  identifier  on  success,  or  false  on  error. 

openssl_get_privatekey()  parses  the  PEM  formatted  private  key  specified  by  key  and  prepares  it  for 
use  by  other  functions.  The  optional  parameter  passphrase  must  be  used  if  the  specified  key  is 
encrypted  (protected  by  a  passphrase). 


openssl_get_publickey  (php  4  >=  4.0.4) 

Extract  public  key  from  certificate  and  prepare  it  for  use 

resource  openssl  get  publickey  (mixed  certificate) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 
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Returns  a  positive  key  resource  identifier  on  success,  or  false  on  error. 

openssI_get_publickey()  extracts  the  public  key  from  an  X.509  certificate  specified  by  certificate 
and  prepares  it  for  use  by  other  functions. 


openssl_open  (php  4  >=  4.o.4) 


Open  sealed  data 


bool  openssl_open  (string  sealed_data,  string  open_data,  string  env_key , 
mixed  priv_key_id ) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


Returns  true  on  success,  or  false  on  error.  If  successful  the  opened  data  is  returned  in  open_data. 

openssl_open()  opens  (decrypts)  sealed_data  using  the  private  key  associated  with  the  key  identifier 
priv_key_id  and  the  envelope  key  env_key,  and  fills  open_data  with  the  decrypted  data.  The 
envelope  key  is  generated  when  the  data  are  sealed  and  can  only  be  used  by  one  specific  private  key.  See 
openssl_seal  )  for  more  information. 


Ejemplo  1.  openssl_open()  example 

//  $sealed  and  $env_key  are  assumed  to  contain  the  sealed  data 
//  and  our  envelope  key,  both  given  to  us  by  the  sealer. 

//  fetch  private  key  from  file  and  ready  it 

$fp  =  f open ( " /src/openssl-0 . 9 . 6/demos/sign/key . pern"  ,  "r"); 

$priv_key  =  fread($fp,  8192); 
fclose ($fp) ; 

$pkeyid  =  openssl_get_privatekey ( $priv_key) ; 

//  decrypt  the  data  and  store  it  in  $open 
if  (openssl_open ($sealed,  $open,  $env_key,  Spkeyid) ) 
echo  "here  is  the  opened  data:  ",  $open; 

else 

echo  "failed  to  open  data"; 

/ /  free  the  private  key  from  memory 
openssl_free_key (Spkeyid)  ; 
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See  also  openssl_seak). 


openssl_seal  (PHP  4  >=  4.0.4) 


Seal  (encrypt)  data 


int  openssl_seal  (string  data,  string  sealed_data,  array  env_keys ,  array 
pub_key_ids) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


Returns  the  length  of  the  sealed  data  on  success,  or  false  on  error.  If  successful  the  sealed  data  is 
returned  in  sealed_data,  and  the  envelope  keys  in  env_keys. 

openssl_seal()  seals  (encrypts)  data  by  using  RC4  with  a  randomly  generated  secret  key.  The  key  is 
encrypted  with  each  of  the  public  keys  associated  with  the  identifiers  in  pub_key_ids  and  each 
encrypted  key  is  returned  in  env_keys.  This  means  that  one  can  send  sealed  data  to  multiple  recipients 
(provided  one  has  obtained  their  public  keys).  Each  recipient  must  receive  both  the  sealed  data  and  the 
envelope  key  that  was  encrypted  with  the  recipient’s  public  key. 


Ejemplo  1.  openssl_seal()  example 

/ /  $data  is  assumed  to  contain  the  data  to  be  sealed 

//  fetch  public  keys  for  our  recipients,  and  ready  them 

$fp  =  fopen (" /src/openssl-0 . 9 . 6/demos/maurice/cert . pern" ,  "r"); 

$cert  =  fread($fp,  8192); 
fclose ( $  f p ) ; 

$pkl  =  openssl_get_publickey ( $cert ) ; 

/ /  Repeat  for  second  recipient 

$fp  =  fopen (" /src/openssl-0 . 9 . 6/demos/sign/cert . pern" ,  "r"); 

$cert  =  fread($fp,  8192); 
fclose ($fp) ; 

$pk2  =  openssl_get_publickey  ( $cert ) ; 

//  seal  message,  only  owners  of  $pkl  and  $pk2  can  decrypt  $sealed  with  keys 

//  $ekeys[0]  and  $ekeys[l]  respectively. 

openssl_seal ($data,  $sealed,  $ekeys,  array ( $pkl , $pk2 )) ; 

/ /  free  the  keys  from  memory 
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openssl_f ree_key ($pkl)  ; 
openssl_f ree_key ( $pk2 )  ; 


See  also  opensslopcn '). 


openssl_sign  (php  4  >=  4.0.4) 


Generate  signature 


bool  openssl_sign  (string  data,  string  signature ,  mixed  priv_key_id) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


Returns  true  on  success,  or  false  on  failure.  If  successful  the  signature  is  returned  in  signature. 

openssl_sign()  computes  a  signature  for  the  specified  data  by  using  SHA1  for  hashing  followed  by 
encryption  using  the  private  key  associated  with  priv_key_id.  Note  that  the  data  itself  is  not 
encrypted. 


Ejemplo  1.  openssl_sign()  example 

//  $data  is  assumed  to  contain  the  data  to  be  signed 
/ /  fetch  private  key  from  file  and  ready  it 

$fp  =  f open ( " /src/openssl-0 . 9 . 6/demos/sign/key . pern" ,  "r"); 

$priv_key  =  fread($fp,  8192); 
fclose ($fp) ; 

$pkeyid  =  openssl_get_privatekey ( $priv_key) ; 

/ /  compute  signature 

openssl_sign ($data,  $signature,  Spkeyid) ; 

/ /  free  the  key  from  memory 
openssl_free_key ($pkeyid)  ; 


See  also  openssl_verify). 
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openssl_verify  (php  4  >=  4.o.4) 


Verify  signature 


int  openssl_verify  (string  data,  string  signature ,  mixed  pub_key_id) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


Returns  1  if  the  signature  is  correct,  0  if  it  is  incorrect,  and  -1  on  error. 

openssl_verify()  verifies  that  the  signature  is  correct  for  the  specified  data  using  the  public  key 
associated  with  pub_key_id.  This  must  be  the  public  key  corresponding  to  the  private  key  used  for 
signing. 


Ejemplo  1.  openssl_verify()  example 

//  $data  and  $signature  are  assumed  to  contain  the  data  and  the  signature 

/ /  fetch  public  key  from  certificate  and  ready  it 

$fp  =  f open (" /src/openssl-0 . 9 . 6/demos/sign/cert . pern" ,  "r"); 

$cert  =  fread($fp,  8192); 
fclose ($fp) ; 

$pubkeyid  =  openssl_get_publickey ($cert) ; 

/ /  state  whether  signature  is  okay  or  not 

$ok  =  openssl_verify ($data,  $signature,  $pubkeyid) ; 

if  ($ok  ==  1) 

echo  "good"; 
elseif  ($ok  ==  0) 
echo  "bad"; 

else 

echo  "ugly,  error  checking  signature"; 

/ /  free  the  key  from  memory 
openssl_free_key ($pubkeyid)  ; 


See  also  openssl_sign(). 
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openssl_pkcs7_decrypt  (php  4  >=  4  o  6) 


Decrypts  an  S/MIME  encrypted  message 


bool  openssl_pkcs7_decrypt  (string  infilename,  string  out  filename,  mixed 
recipcert ,  mixed  recipkey) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


Decrypts  the  S/MIME  encrypted  message  contained  in  the  file  specified  by  infilename  using  the 
certificate  and  it’s  associated  private  key  specified  by  recipcert  and  recipkey. 

The  decrypted  message  is  output  to  the  file  specified  by  out  filename 


Ejemplo  1.  openssl_pkcs7_decrypt()  example 

/ /  $cert  and  $key  are  assumed  to  contain  your  personal  certificate  and  private 
//  key  pair,  and  that  you  are  the  recipient  of  an  S/MIME  message 
$infilename  =  "encrypted. msg" ;  //  this  file  holds  your  encrypted  message 

$outfilename  =  "decrypted . msg" ;  //  make  sure  you  can  write  to  this  file 

if  (openssl_pkcs7_decrypt ($infilename,  $outf ilename,  $cert,  $key) ) 
echo  "decrypted!"; 

else 

echo  "failed  to  decrypt!"; 


Nota:  This  function  was  added  in  4.0.6. 


openssl_pkcs7_encrypt  (php  4  >=  4.o.6) 


Encrypt  an  S/MIME  message 


bool  openssl_pkcs7_encrypt  (string  infilename,  string  out  filename,  mixed 
recipcerts,  array  headers  f,  long  flags]) 
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Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


openssl_pkcs7_encrypt()  takes  the  contents  of  the  file  named  in  filename  and  encrypts  them  using 
an  RC2  40-bit  cipher  so  that  they  can  only  be  read  by  the  intended  recipients  specified  by  recipcerts, 
which  is  either  a  lone  X.509  certificate,  or  an  array  of  X.509  certificates,  headers  is  an  array  of 
headers  that  will  be  prepended  to  the  data  after  it  has  been  encrypted,  flags  can  be  used  to  specify 
options  that  affect  the  encoding  process  -  see  PKCS7  constants  headers  can  be  either  an  associative 
array  keyed  by  header  name,  or  an  indexed  array,  where  each  element  contains  a  single  header  line. 


Ejemplo  1.  openssl_pkcs7_encrypt()  example 

//  the  message  you  want  to  encrypt  and  send  to  your  secret  agent 
//  in  the  field,  known  as  nighthawk .  You  have  his  certificate 
//  in  the  file  nighthawk . pern 
$data  =  <<<EOD 
Nighthawk, 

Top  secret,  for  your  eyes  only! 

The  enemy  is  closing  in!  Meet  me  at  the  cafe  at  8.30am 
to  collect  your  forged  passport ! 

HQ 
EOD ; 

/ /  save  message  to  file 
$fp  =  f open ( "msg . txt " ,  "w"); 

fwrite($fp,  $data) ; 
fclose ($fp) ; 

/ /  encrypt  it 

if  (openssl_pkcs7_encrypt ( "msg . txt " ,  "enc.txt ",  "nighthawk . pem" , 
array ("To"  =>  "nighthawk@agent.com",  //  keyed  syntax 
"From:  HQ  <hq@ cia . com> " ,  //  indexed  syntax 

"Subject"  =>  "Eyes  only"))) 

{ 

//  message  encrypted  -  send  it! 

exec (ini  get ( " sendmail  path")  .  "  <  enc.txt"); 

} 


Nota:  This  function  was  added  in  4.0.6. 
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openssl_pkcs7_sign  (php4>=4  0  6) 


sign  an  S/MIME  message 


bool  openssl  pkcs7  sign  (string  in  filename ,  string  out  filename,  mixed 
signcert,  mixed  privkey ,  array  headers  [,  long  flags  [,  string 
extracerts filename] ] ) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


openssl_pkcs7_sign()  takes  the  contents  of  the  file  named  in  filename  and  signs  them  using  the 
certificate  and  it’s  matching  private  key  specified  by  signcert  and  privkey  parameters. 

headers  is  an  array  of  headers  that  will  be  prepended  to  the  data  after  it  has  been  signed  (see 
openssl_pkcs7_encrypt')  for  more  information  about  the  format  of  this  parameter. 

flags  can  be  used  to  alter  the  output  -  see  PKCS7  constants  -  if  not  specified,  it  defaults  to 
PKCS7_DETACHED. 

extracerts  specifies  the  name  of  a  file  containing  a  bunch  of  extra  certificates  to  include  in  the 
signature  which  can  for  example  be  used  to  help  the  recipient  to  verify  the  certificate  that  you  used. 


Ejemplo  1.  openssl_pkcs7_sign()  example 

//  the  message  you  want  to  sign  so  that  recipient  can  be  sure  it  was  you  that 
/ /  sent  it 
$data  =  <<<EOD 

You  have  my  authorization  to  spend  $10,000  on  dinner  expenses. 

The  CEO 
EOD ; 

/ /  save  message  to  file 
$fp  =  f open ( "msg . txt " ,  "w"); 

fwrite($fp,  $data) ; 
fclose ($fp) ; 

/ /  encrypt  it 

if  (openssl_pkcs7_sign ( "msg . txt " ,  "signed.txt",  "mycert . pern" , 
array ( "mycert . pern" ,  "mypassphrase" ) , 
array ("To"  =>  "joes@sales.com",  //  keyed  syntax 

"From:  HQ  <ceo@sales . com>" ,  //  indexed  syntax 

"Subject"  =>  "Eyes  only")) 

{ 

//  message  signed  -  send  it! 
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exec (ini  get ( " sendmail  path")  .  "  <  signed.txt"); 

} 


Nota:  This  function  was  added  in  4.0.6. 


openssl_pkcs7_verify  (php  4  >=  4.0.6) 


Verifies  the  signature  of  an  S/MIME  signed  message 


bool  openssl  pkcs7  verify  (string  filename,  int  flags  [,  string  out  filename 
[,  array  cainfo  [,  string  extracerts]]]) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


openssl_pkcs7_verify()  reads  the  S/MIME  message  contained  in  the  filename  specified  by  filename 
and  examines  the  digital  signature.  It  returns  true  if  the  signature  is  verified,  false  if  it  is  not  correct 
(the  message  has  been  tampered  with,  or  the  signing  certificate  is  invalid),  or  -1  on  error. 

flags  can  be  used  to  affect  how  the  signature  is  verified  -  see  PKCS7  constants  for  more  information. 

If  the  out  filename  is  specified,  it  should  be  a  string  holding  the  name  of  a  file  into  which  the 
certificates  of  the  persons  that  signed  the  messages  will  be  stored  in  PEM  format. 

If  the  cainfo  is  specified,  it  should  hold  information  about  the  trusted  CA  certificates  to  use  in  the 
verification  process  -  see  certificate  verification  for  more  information  about  this  parameter. 

If  the  extracerts  is  specified,  it  is  the  filename  of  a  file  containing  a  bunch  of  certificates  to  use  as 
untrusted  CAs. 

Nota:  This  function  was  added  in  4.0.6. 
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openssl_x509_checkpurpose  (php  4  >=  4  o  6> 


Verifies  if  a  certificate  can  be  used  for  a  particular  purpose 


bool  openssl_x509_checkpurpose  (mixed  x509cert,  int  purpose,  array  cainfo  [, 
string  untrustedfile]  ) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


Returns  true  if  the  certificate  can  be  used  for  the  intended  purpose,  false  if  it  cannot,  or  -1  on  error. 

openssl_x509_checkpurpose()  examines  the  certificate  specified  by  x509cert  to  see  if  it  can  be  used 
for  the  purpose  specified  by  purpose. 

cainfo  should  be  an  array  of  trusted  CA  files/dirs  as  described  in  Certificate  Verification 

untrustedfile ,  if  specified,  is  the  name  of  a  PEM  encoded  file  holding  certificates  that  can  be  used 
to  help  verify  the  certificate,  although  no  trust  in  placed  in  the  certificates  that  come  from  that  file. 


Tabla  1.  openssl_x509_checkpurpose()  purposes 


Constant 

Description 

X509_PURPOSE_SSL_CLIENT 

Can  the  certificate  be  used  for  the  client  side  of  an 

SSL  connection? 

X509_PURPOSE_SSL_SERVER 

Can  the  certificate  be  used  for  the  server  side  of  an 

SSL  connection? 

X509 PURPOSE NS SSL SERVER 

Can  the  cert  be  used  for  Netscape  SSL  server? 

X509 PURPOSE SMIME SIGN 

Can  the  cert  be  used  to  sign  S/MIME  email? 

X509 PURPOSE SMIME ENCRYPT 

Can  the  cert  be  used  to  encrypt  S/MIME  email? 

X509_PURPOSE_CRL_SIGN 

Can  the  cert  be  used  to  sign  a  certificate  revocation 
list  (CRL)? 

X509_PURPOSE_ANY 

Can  the  cert  be  used  for  Any/ All  purposes? 

These  options  are  not  bitfields  -  you  may  specify  one  only! 
Nota:  This  function  was  added  in  4.0.6. 
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openssl_x509_f  ree  (php  4  >=  4.0.6) 


Free  certificate  resource 


void  open ssl_x509_f ree  (resource  x509cert) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


openssl_x509_free()  frees  the  certificate  associated  with  the  specified  x50 9 cert  resource  from 
memory. 

Nota:  This  function  was  added  in  4.0.6. 


openssl_x509_parse  (php  4  >=  4.0.6) 

Parse  an  X509  certificate  and  return  the  information  as  an  array 

array  openssl_x509_parse  (mixed  x509cert  [,  bool  shortnames]) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


openssl_x509_parse()  returns  information  about  the  supplied  x509cert,  including  fields  such  as 
subject  name,  issuer  name,  purposes,  valid  from  and  valid  to  dates  etc.  shortnames  controls  how  the 
data  is  indexed  in  the  array  -  if  shortnames  is  true  (the  default)  then  fields  will  be  indexed  with  the 
short  name  form,  otherwise,  the  long  name  form  will  be  used  -  e.g.:  CN  is  the  shortname  form  of 
commonName. 

The  structure  of  the  returned  data  is  ( deliberately )  not  yet  documented,  as  it  is  still  subject  to  change. 

Nota:  This  function  was  added  in  4.0.6. 
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openssl_x509_read  (php  4  >=  4.0.6) 


Parse  an  X.509  certificate  and  return  a  resource  identifier  for  it 


resource  opens sl_x509_read  (mixed  x509certdata ) 


Aviso 

This  function  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  this  function, 
this  function  name,  in  concreto  ANYTHING  documented  here  can  change  in  a 
future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this  function  at 
your  own  risk. 


openssl_x509_read()  parses  the  certificate  supplied  by  x50 9certdata  and  returns  a  resource 
identifier  for  it. 

Nota:  This  function  was  added  in  4.0.6. 
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Ora_Bind  (PHP  3,  PHP  4  >=  4.0.0) 


Vincula  una  variable  PHP  a  un  parametro  Oracle 


int  ora_bind  (int  cursor,  string  nombre  de  variable  PHP,  string  nombre  de 
parametro  SQL,  int  longitud  [,  int  tipo ]) 


Devuelve  verdadero  si  el  vinculo  se  realiza  con  exito,  y  sino  devuelve  falso.  Los  detalles  de  los  errores 
pueden  examinarse  usando  la  funciones  ora_error  ')  y  ora_errorcode'). 

Esta  funcion  liga  la  variable  PHP  nombrada  con  el  parametro  SQL.  El  paramtro  SQL  debe  estar  en  la 
forma  ":name".  Con  el  parametro  optativo  tipo,  se  define  si  el  parametro  SQL  se  trata  de  un  parametro  de 
entrada/salida  (0  y  por  defecto),  entrada  (1)  o  salida  (2).  Como  en  PHP  3.0.1,  se  puede  usar  las 
constantes  ORA_BIND_INOUT,  ORA_BIND_IN  y  ORA_BIND_OUT  en  lugar  de  los  numeros. 

ora_bind  debe  ser  llamada  despues  de  ora_parse ')  y  antes  de  ora_exec').  Los  valores  de  entrada  pueden 
pasarse  por  asignacion  a  las  variables  PHP  vinculadas,  despues  de  la  llamada  a  ora_exec ')  dichas 
variables  contendran  los  valores  de  salida,  si  estos  estuvieran  disponibles. 

<?php 

ora_parse ( $curs ,  "declare  tmp  INTEGER;  begin  tmp  :=  :in;  : out  :=  tmp;  :x  :=  7.77; 
ora_bind ( $curs ,  "result",  ":x",  $len,  2); 
ora_bind ( $curs ,  "input",  ":in",  5,  1); 
ora_bind ( $curs ,  "output",  ":out",  5,  2); 

$input  =  765; 
ora_exec ( $curs ) ; 

echo  "Result:  $result<BR>Out :  $output<BR>In :  $input"; 

?> 


Ora_Close  (PHP  3,  PHP  4  >=4.0.0) 

Cierra  un  cursor  Oracle 

int  ora_close  (int  cursor ) 

Devuelve  verdadero  si  el  cierre  fue  exitoso,  o  falso  de  lo  contrario.  Los  detalles  de  los  errores  se 
recuperan  usando  las  funciones  ora_error ')  y  ora_errorcode0- 

Esta  funcion  cierra  un  cursor  de  datos  abierto  con  ora_opcn 


end 
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Ora_ColumnName  (PHP  3,  PHP  4  >=  4.0.0) 

toma  el  nombre  de  una  columna  de  resultados  Oracle 

string  Ora_ColumnName  (int  cursor,  int  column) 

Devuelve  el  nomre  de  un  campo/columna  column  en  el  cursor  cursor,  el  nombre  devuelto  estara  en 
letras  mayusculas. 


Ora_ColumnType  (PHP  3,  PHP  4  >=4.0.0) 

toma  el  tipo  de  una  columna  de  resultados  Oracle 

string  Ora_ColumnType  (int  cursor,  int  column) 


Devuelve  el  nombre  del  tipo  de  datos  del  campo  o  columna  column  en  el  cursor  cursor.  Se  devolvera 
un  tipo  de  datos,  de  entre  los  siguientes: 

"VARCHAR2 " 

"VARCHAR" 

"CHAR" 

"NUMBER" 

"LONG" 

"LONG  RAW" 

"ROWID" 

"DATE" 

"CURSOR" 


Ora_Commit  (PHP  3,  PHP  4  >=  4.0.0) 

realiza  una  transaction  Oracle 


int  ora_cominit  (int  conn) 


Devuelve  verdadero  si  es  exitosa,  de  lo  cantrario  devuelve  falso.  Puede  verse  los  detalles  del  error  usando 
las  funciones  ora_errorJ)  y  ora_errorcode0-  Esta  funcion  realiza  una  transaction  Oracle.  Se  define  como 
transaction  cualquier  cambio  en  una  conexion  dada,  desde  la  ultima  tarea/retroceso  en  la  ejecucion 
(rollback),  anulacion  de  la  ejecucion  automatica  de  tareas  (autocommit),  o  cuando  se  ha  establecido  la 
conexion. 
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Ora_CommitOff  (PHP  3,  PHP  4  >=  4.0.0) 

deshabilita  el  modo  automatico  de  ejecucion  de  tareas  (autocommit) 

int  ora_coimnitof f  (int  conn ) 

Devuelve  verdadero  si  se  ejecuta  con  exito,  sino  devuelve  falso.  Los  pormenores  del  error  en  cuestion, 
pueden  revisarse  invocando  las  funciones  ora_errorj  y  ora_errorcode'). 

Esta  funcion  deshabilita  la  ejecucion  automatica  luego  de  cada  instancia  ora_exec '). 

Ora_CommitOn  (PHP  3,  PHP  4  >=  4.0.0) 

Habilita  la  ejecucion  automatica  de  tareas  (autocommit) 

int  ora_cominiton  (int  conn ) 

Esta  funcion  habilita  la  ejecucion  automatica  luego  de  cada  instancia  ora_exec ')  en  la  conexion  dada. 

Devuelve  verdadero  si  se  ejecuta  con  exito,  sino  devuelve  falso.  Los  pormenores  del  error  en  cuestion, 
pueden  revisarse  invocando  las  funciones  ora_crrorj  y  ora_errorcode'). 

Ora_Error  (PHP  3,  PHP  4  >=  4.0.0) 

toma  los  mensajes  de  error  de  Oracle 

string  Orajrror  (int  cursor_or_connection) 

Devuelve  los  mensajes  de  error  en  la  forma  XXX-NNNNN  donde  XXX  es  la  procedencia  del  error  y 
NNNNN  es  la  identification  del  mensaje  de  error. 

Nota:  El  soporte  para  las  identificaciones  de  conexion  fue  agregado  en  la  version  3.0.4. 


En  las  versiones  UNIX  de  Oracle,  pueden  encontrarse  detalles  acerca  de  un  mensaje  de  error  como  este: 

$  oerr  ora  00001  00001,  00000,  "unique  constraint  (%s.%s)  violated"  // 
*Cause:  An  update  or  insert  statement  attempted  to  insert  a  duplicate  key  // 
For  Trusted  ORACLE  configured  in  DBMS  MAC  mode,  you  may  see  //  this  message 
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if  a  duplicate  entry  exists  at  a  different  level.  //  *Action:  Either  remove 
the  unique  restriction  or  do  not  insert  the  key 


Ora_ErrorCode  (PHP  3,  PHP  4  >=  4.0.0) 

captura  el  codigo  de  error  Oracle 

int  Ora_ErrorCode  (int  cursor_or_connection) 


Devuelve  el  codigo  numerico  de  error  de  la  ultima  declaracion  ejecutada  en  el  cursor  o  conexion 
espacificada. 

*  FIXME:  se  listaran  los  valores  posibles? 

Nota:  El  soporte  para  las  identificaciones  de  conexion  fue  agregado  en  la  version  3.0.4. 


Ora_Exec  (PHP  3,  PHP  4  >=  4.0.0) 

ejecuta  las  declaraciones  interpretadas  en  un  cursor  Oracle 

int  ora_exec  (int  cursor) 


Devuelve  verdadero  ante  la  ejecucion  exitosa,  de  lo  contrario,  devuelve  falso.  Los  detalles  del  error 
pueden  verse  invocando  las  funciones  ora_error')  y  ora_errorcode '). 


Ora_Fetch  (PHP  3,  PHP  4  >=  4.0.0) 

extrae  una  fila  de  datos  a  partir  de  un  cursor 

int  ora_fetch  (int  cursor) 


Devuelve  verdadero  (se  extrajo  una  fila)  o  falso  (no  hay  mas  filas,  o  ha  ocurrido  un  error).  Si  ocurre  un 
error,  los  detalles  del  mismo  pueden  verse  invocando  las  funciones  ora_error')  y  ora_errorcode  ')-  Si  no 
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hubo  errores,  ora_errorcode  )  devolvera  0.  Recupera  una  hilera  de  datos  partiendo  de  un  cursor 
especificado. 


Ora_GetColumn  (PHP  3,  PHP  4  >=  4.0.0) 


toma  datos  de  la  fila  extrafda 


mixed  ora_getcolumn  (int  cursor,  mixed  column) 


Devuelve  la  columna  de  datos.  Si  hay  un  error,  se  devuelve  falso  y  ora_errorcodeO  devulve  un  valor 
distinto  de  cero.  Note,  de  igual  manera,  que  la  busqueda  de  un  resultado  Falso  en  esta  funcion,  puede 
resultar  verdadera,  aun  en  casos  en  que  no  ocurran  errores: (resultado  NULO,  cadenas  vacias,  valor  0  o 
cadenas  "0").  Extrae  los  datos  para  una  columna  o  resultado  de  funcion. 


Ora_Logoff  (PHP  3,  PHP  4  >=4.0.0) 

cierra  una  conexion  Oracle 

int  ora_logoff  (int  connection) 

Devuelve  verdadero  si  es  exitosa,  o  falso  si  hay  errores.  Los  detalles  del  error  pueden  verse  invocando  las 
funciones  ora_crror')  y  ora_errorcode ').  Cierra  la  sesion  de  trabajo  del  usuario,  y  lo  desconecta  del 
servidor. 


Ora_Logon  (PHP  3,  PHP  4  >=4.0.0) 

Abre  una  conexion  Oracle 

int  ora_logon  (string  usuario,  string  contrasena) 


Establece  una  conexion  entre  PHP  y  una  base  de  datos  Oracle,  con  los  datos  de  nombre  de  usuario  y 
contrasena  especificados. 

Las  conexiones  pueden  llevarse  adelante  usando  SQL*Net  indicando  el  nombre  TNS  al  usuario  de 
este  modo: 

$conn  =  Ora_Logon ( " usuario 0TNSNAME" ,  "contrasena") ; 
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Si  hubiesen  datos  con  caracteres  no-ASCII,  habrfa  que  asegurarse  de  que  este  presente  la  variable  de 
entorno  NLSJLANG  en  el  sistema.  Para  los  modulos  de  servidor,  deberfan  definirse  en  el  entorno  del 
servidor  antes  de  iniciarlo. 

Devuelve  el  mdice  de  la  conexion  si  aquella  tuvo  exito,  de  lo  cantrario  devuelve  falso.  Los  detalles  del 
error  pueden  verse  invocando  las  funciones  ora_error')  y  ora_errorcode '). 


Ora_Operi(PHP3 


PHP  4  >=  4.0.0) 


abre  un  cursor  Oracle 


int  ora_open  (int  connection) 


Abre  un  cursor  asociado  con  la  conexion. 

Devuelve  el  mdice  del  cursor  o  Falso  si  hay  un  error.  Los  detalles  del  error  pueden  verse  invocando  las 
funciones  ora_errorj  y  ora  errorcode '). 


Ora_Parse  (PHP  3,  PHP  4  >=4.0.0) 

interpreta  una  declaracion  SQL 

int  ora  parse  (int  cursor_ind,  string  sql_statement ,  int  defer ) 


Esta  funcion  interpreta  una  declaracion  SQL  o  un  bloque  PL/SQL  y  los  asocia  con  el  cursor  dado. 
Devuelve  0  si  se  ejecuta  con  exito,  o  -1  ante  un  error. 


Ora_Rollback  (PHP  3,  PHP  4  >=  4.0.0) 

retrocede  en  la  lista  de  transacciones  (hace  un  roll  back) 

int  ora_rollback  (int  connection ) 


Deshace  una  transaccion  Oracle.  (Ver  ora_commit0  para  la  definicion  de  transaccion.) 
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Devuelve  verdadero  si  tiene  exito,  o  falso  si  hay  un  error.  Los  detalles  del  error  pueden  verse  invocando 
las  funciones  ora_error')  y  ora_errorcodeO. 
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Ovrimos  SQL  Server,  is  a  client/server,  transactional  RDBMS  combined  with  Web  capabilities  and  fast 
transactions. 

Ovrimos  SQL  Server  is  available  at  www.ovrimos.com (http://www.ovrimos.com/).  To  enable  ovrimos 
support  in  PHP  just  compile  php  with  the  with-ovrimos’  parameter  to  configure  script.  You’ll  need  to 
install  the  sqlcli  library  available  in  the  Ovrimos  SQL  Server  distribution. 


Ejemplo  1.  Connect  to  Ovrimos  SQL  Server  and  select  from  a  system  table 


<?php 

$conn  =  ovrimos_connect  ("server.domain.com",  "8001",  "admin",  "password"); 
if  ($conn  !=  0)  { 

echo  ("Connection  ok ! " ) ; 

$res  =  ovrimos_exec  ($conn,  "select  table_id,  table_name  from  sys . tables") 
if  ($res  !=  0)  { 

echo  "Statement  ok ! " ; 
ovrimos_result_all  ($res); 
ovrimos_f ree_result  ($res) ; 

} 

ovrimos_close ($conn) ; 


?> 


This  will  just  connect  to  SQL  Server. 
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ovrimos_connect  (php  4  >=  4.o.3) 


Connect  to  the  specified  database 


int  ovrimos_connect  (string  host,  string  db,  string  user,  string  password) 


ovrimos_connect()  is  used  to  connect  to  the  specified  database. 

ovrimos_connect()  returns  a  connection  id  (greater  than  0)  or  0  for  failure.  The  meaning  of  ’host’  and 
’port’  are  those  used  everywhere  in  Ovrimos  APIs.  ’Host’  is  a  host  name  or  IP  address  and  ’db’  is  either 
a  database  name,  or  a  string  containing  the  port  number. 


Ejemplo  1.  ovrimos_connect()  Example 


<?php 

$conn  =  ovrimos_connect  ("server.domain.com",  "8001",  "admin",  "password") ; 
if  ($conn  !=  0)  { 

echo  "Connection  ok!"; 

$res=ovrimos_exec  ($conn,  "select  table_id,  table_name  from  sys . tables ") ; 
if  ($res  !=  0)  { 

echo  "Statement  ok ! " ; 
ovrimos_result_all  ($res); 
ovrimos_f ree_result  ($res) ; 

} 

ovrimos_close  ($conn); 


?> 


The  above  example  will  connect  to  the  database  and  print  out  the  specified  table. 


ovrimos_close  (php  4  >=  4  o  3> 

Closes  the  connection  to  ovrimos 

void  ovrimos_close  (int  connection) 

ovrimos_close()  is  used  to  close  the  specified  connection. 

ovrimos_close()  closes  a  connection  to  Ovrimos.  This  has  the  effect  of  rolling  back  uncommitted 
transactions. 
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ovrimos_close_all  (4 .0 .3  4 .0 ,6 oniy) 


Closes  all  the  connections  to  ovrimos 


void  ovrimos_close_all  (void) 


ovrimos_close_all()  is  used  to  close  all  the  connections. 

ovrimos_close_all()  closes  all  connections  to  Ovrimos.  This  has  the  effect  of  rolling  back  uncommitted 
transactions. 


ovrimosjongreadlen  (php  4  >=  4  0  3) 

Specifies  how  many  bytes  are  to  be  retrieved  from  long  datatypes 

int  ovrimos_longreadlen  (int  result_id,  int  length ) 


ovrimos_longreadlen()  is  used  to  specify  how  many  bytes  are  to  be  retrieved  from  long  datatypes. 

ovrimos_longreadlen()  specifies  how  many  bytes  are  to  be  retrieved  from  long  datatypes  (long  varchar 
and  long  varbinary).  Default  is  zero.  Regardless  of  its  taking  a  result_id  as  an  argument,  it  currently  sets 
this  parameter  for  all  result  sets.  Returns  true. 


ovrimos_prepare  (PHP4>=4.0.3) 


Prepares  an  SQL  statement 


int  ovrimos  prepare  (int  connection_id,  string  query) 


ovrimos_prepare()  is  used  to  prepare  an  SQL  statement. 

ovrimos_prepare()  prepares  an  SQL  statement  and  returns  a  result_id  (or  false  on  failure). 


Ejemplo  1.  Connect  to  Ovrimos  SQL  Server  and  prepare  a  statement 

<?php 

$conn=ovrimos_connect  ("db_host",  "8001",  "admin",  "password"); 
if  ($conn!=0)  { 

echo  "Connection  ok!"; 

$res=ovrimos_prepare  ($conn,  "select  table_id,  table_name 
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from  sys. tables  where  table_id=l " ) ; 

if  ($res  !=  0)  { 

echo  "Prepare  ok!"; 
if  (ovrimos_execute  ($res) )  { 

echo  "Execute  ok!\n"; 
ovrimos_result_all  ($res) ; 

}  else  { 

echo  "Execute  not  ok!"; 

} 

ovrimos_f ree_result  ($res) ; 

}  else  { 

echo  "Prepare  not  ok!\n"; 

} 

ovrimos_close  ($conn); 

} 

?> 

This  will  connect  to  Ovrimos  SQL  Server,  prepare  a  statement  and  the  execute  it. 


ovrimos_execute  (php  4  >=  4  o  3> 

Executes  a  prepared  SQL  statement 

int  ovrimos_execute  (int  result_id  [,  array  parameter s_array ]) 


ovrimos_execute()  is  used  to  execute  an  SQL  statement. 

ovrimos_execute()  executes  a  prepared  statement.  Returns  true  or  false.  If  the  prepared  statement 
contained  parameters  (question  marks  in  the  statement),  the  correct  number  of  parameters  should  be 
passed  in  an  array.  Notice  that  I  don’t  follow  the  PHP  convention  of  placing  just  the  name  of  the  optional 
parameter  inside  square  brackets.  I  couldn’t  bring  myself  on  liking  it. 


ovrimos_cursor  (php  4  >=  4.0.3) 

Returns  the  name  of  the  cursor 

int  ovrimos_cursor  (int  result_id) 

ovrimos_cursor()  is  used  to  get  the  name  of  the  cursor. 

ovrimos_cursor()  returns  the  name  of  the  cursor.  Useful  when  wishing  to  perform  positioned  updates  or 
deletes. 
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ovrimos_exec  (php  4  >=  4.0.3) 

Executes  an  SQL  statement 

int  ovrimos_exec  (int  connection_id,  string  query) 

ovrimos_exec()  is  used  to  execute  an  SQL  statement. 

ovrimos_exec()  executes  an  SQL  statement  (query  or  update)  and  returns  a  result_id  or  false. 
Evidently,  the  SQL  statement  should  not  contain  parameters. 


ovrimos_fetch  intO(PHP4>=4.o.3) 


Letches  a  row  from  the  result  set 


int  ovrimos_fetch_into  (int  result_id,  array  result_array  [,  string  how  [, 
int  rownumber] ] ) 


ovrimos_fetch_into()  is  used  to  fetch  a  row  from  the  result  set. 

ovrimos_fetch_into()  fetches  a  row  from  the  result  set  into  ’result_array\  which  should  be  passed  by 
reference.  Which  row  is  fetched  is  determined  by  the  two  last  parameters,  ’how’  is  one  of  ’Next’ 
(default),  ’Prev’,  ’Lirst’,  ’Last’,  ’Absolute’,  corresponding  to  forward  direction  from  current  position, 
backward  direction  from  current  position,  forward  direction  from  the  start,  backward  direction  from  the 
end  and  absolute  position  from  the  start  (essentially  equivalent  to  ’first’  but  needs  ’rownumber’).  Case  is 
not  significant.  ’Rownumber’  is  optional  except  for  absolute  positioning.  Returns  true  or  false. 


Ejemplo  1.  A  fetch  into  example 

<?php 

$conn=ovrimos_connect  ("neptune",  "8001",  "admin",  "password"); 
if  ($conn!=0)  { 

echo  "Connection  ok!"; 

$res=ovrimos_exec  ($conn, "select  table_id,  table_name  from  sys . tables ") ; 
if  ($res  !=  0)  { 

echo  "Statement  ok!"; 

if  (ovrimos_f etch_into  ($res,  &$row) )  { 

list  ($table_id,  $table_name)  =  $row; 

echo  "table_id=" . $table_id . " ,  table_name=" . $table_name . " \n" ; 
if  (ovrimos_fetch_into  ($res,  &$row) )  { 

list  ($table_id,  $table_name)  =  $row; 

echo  "table_id=" . $table_id . " ,  table_name=" . $table_name . " \n" ; 
}  else  { 

echo  "Next:  error\n"; 
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} 

}  else  { 

echo  "First:  error\n"; 

} 

ovrimos_f ree_result  ($res) ; 

} 

ovrimos_close  ($conn); 

} 

?> 


This  example  will  fetch  a  row. 


ovrimos_fetch_row  (php  4  >=  4.0.3) 

Fetches  a  row  from  the  result  set 

int  ovrimos_fetch_row  (int  result_id  [,  int  how  [,  int  row_number] ] ) 


ovrimos_fetch_row()  is  used  to  fetch  a  row  from  the  result  set. 

ovrimos_fetch_row()  fetches  a  row  from  the  result  set.  Column  values  should  be  retrieved  with  other 
calls.  Returns  true  or  false. 


Ejemplo  1.  A  fetch  row  example 

<?php 

$conn  =  ovrimos_connect  (" remote . host " ,  "8001",  "admin",  "password") ; 

if  ($conn  !=  0)  { 

echo  "Connection  ok!"; 

$res=ovrimos_exec  ($conn,  "select  table_id,  table_name  from  sys . tables ") ; 
if  ($res  !=  0)  { 

echo  "Statement  ok ! " ; 

if  (ovrimos_fetch_row  ($res,  "First"))  { 

$table_id  =  ovrimos_result  ($res,  1) ; 

$table_name  =  ovrimos_result  ($res,  2); 

echo  "table_id=" . $table_id . " ,  table_name=" . $table_name . " \n" ; 
if  (ovrimos_fetch_row  ($res,  "Next"))  { 

$table_id  =  ovrimos_result  ($res,  "table_id"); 

$table_name  =  ovrimos_result  ($res,  "table_name" ) ; 

echo  "table_id=" . $table_id . " ,  table_name=" . $table_name . " \n" ; 

}  else  { 

echo  "Next:  error\n"; 


}  else  { 

echo  "First:  error\n"; 

} 
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ovrimos_f ree_result  ($res) ; 

} 

ovrimos_close  ($conn) ; 

} 

?> 


This  will  fetch  a  row  and  print  the  result. 


ovrimos_result  (php  4  >=  4.o.3) 

Retrieves  the  output  column 

int  ovrimos_result  (int  result_id,  mixed  field) 

ovrimos_result()  is  used  to  retrieve  the  output  column. 

ovrimos_result()  retrieves  the  output  column  specified  by  ’field’,  either  as  a  string  or  as  an  1-based 
index. 


ovrimos_result_all  (php  4  >=  4.0.3) 

Prints  the  whole  result  set  as  an  HTML  table 

int  ovrimos_result_all  (int  result_id  [,  string  format]) 


ovrimos_result_all()  is  used  to  print  an  HTML  table  containing  the  whole  result  set. 
ovrimos_result_all()  prints  the  whole  result  set  as  an  HTML  table.  Returns  true  or  false. 


Ejemplo  1.  Prepare  a  statement,  execute,  and  view  the  result 

<?php 

$conn  =  ovrimos_connect  ("db_host",  "8001",  "admin",  "password"); 
if  ($conn  !=  0)  { 

echo  "Connection  ok!"; 

$res  =  ovrimos_prepare  ($conn,  "select  table_id,  table_name 

from  sys. tables  where  table_id  =  7"); 

if  ($res  !=  0)  { 

echo  "Prepare  ok!"; 

if  (ovrimos_execute  ($res,  array(3)))  { 
echo  "Execute  ok!\n"; 
ovrimos_result_all  ($res) ; 
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}  else  { 

echo  "Execute  not  ok ! "  ; 

} 

ovrimos_f ree_result  ($res) ; 

}  else  { 

echo  "Prepare  not  ok!\n"; 

} 

ovrimos_close  ($conn); 

} 

?> 

This  will  execute  an  SQL  statement  and  print  the  result  in  an  HTML  table. 


Ejemplo  2.  Ovrimos_result_all  with  meta-information 

<?php 

$conn  =  ovrimos_connect  ("db_host",  "8001",  "admin",  "password"); 
if  ($conn  !=  0)  { 

echo  "Connection  ok!"; 

$res  =  ovrimos_exec  ($conn,  "select  table_id,  table_name 

from  sys . tables  where  table_id  =  1") 

if  ($res  !=  0)  { 

echo  "Statement  ok!  cursor=" . ovrimos_cursor  ($res)."\n"; 

$colnb  =  ovrimos_num_f ields  ($res); 
echo  "Output  columns=" . $colnb . " \n" ; 
for  ($1=1;  $i<=$colnb;  $i++)  { 

$name  =  ovrimos_f ield_name  ($res,  $i); 

$type  =  ovrimos_f ield_type  ($res,  $i)  ; 

$len  =  ovrimos_f ield_len  ($res,  $i); 

echo  "Column  name=" . $name . "  type=" . $type . "  len=" . $len . " \n" ; 

} 

ovrimos_result_all  ($res); 
ovrimos_f ree_result  ($res) ; 

} 

ovrimos_close  ($conn); 

} 

?> 


Ejemplo  3.  ovrimos_result_all  example 

<?php 

$conn  =  ovrimos_connect  ("db_host",  "8001",  "admin",  "password"); 
if  ($conn  !=  0)  { 

echo  "Connection  ok!"; 

$res  =  ovrimos_exec  ($conn,  "update  test  set  i=5"); 
if  ($res  !=  0)  { 

echo  "Statement  ok!"; 

echo  ovrimos_num_rows  ($res) . "  rows  affected\n"; 
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ovrimos_f ree_result  ($res) ; 

} 

ovrimos_close  ($conn) ; 

} 

?> 


ovrimos_num_rows  (php  4  >=  4.o.3) 

Returns  the  number  of  rows  affected  by  update  operations 

int  ovrimos_num_rows  (int  result_id) 

ovrimos_num_rows()  is  used  to  get  the  number  of  rows  affected  by  update  operations. 
ovrimos_num_rows()  returns  the  number  of  rows  affected  by  update  operations. 

ovrimos_num_f  ields  (php  4  >=  4  o  3> 

Returns  the  number  of  columns 

int  ovrimos_num_f ields  (int  result_id) 

ovrimos_num_fields()  is  used  to  get  the  number  of  columns. 

ovrimos_num_fields()  returns  the  number  of  columns  in  a  result_id  resulting  from  a  query. 

ovrimos_f  ield_name  (php  4  >=  4.0.3) 

Returns  the  output  column  name 

int  ovrimos_f ield_name  (int  result_id,  int  field_number) 

ovrimos_lield_name()  is  used  to  get  the  output  column  name. 

ovrimos_field_name()  returns  the  output  column  name  at  the  (1 -based)  index  specified. 
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ovrimos_f  ield_type  (php  4  >=  4.0.3) 

Returns  the  (numeric)  type  of  the  output  column 

int  ovrimos_f ield_type  (int  result_id,  int  field_number) 

ovrimos_field_type()  is  used  to  get  the  (numeric)  type  of  the  output  column. 

ovrimos_field_type()  returns  the  (numeric)  type  of  the  output  column  at  the  (1-based)  index  specified. 

ovrimos_f  ieldjen  (php  4  >=  4.o.3) 

Returns  the  length  of  the  output  column 

int  ovrimos_f ield_len  (int  result_id,  int  field_number ) 

ovrimos_field_len()  is  used  to  get  the  length  of  the  output  column. 

ovrimos_field_len()  returns  the  length  of  the  output  column  at  the  (1-based)  index  specified. 

ovrimos_f  ield_num  (php  4  >=  4.0.3) 

Returns  the  ( 1  -based)  index  of  the  output  column 

int  ovrimos_f ield_num  (int  result_id,  string  field_name ) 

ovrimos_field_num()  is  used  to  get  the  (1-based)  index  of  the  output  column. 

ovrimos_field_num()  returns  the  (1-based)  index  of  the  output  column  specified  by  name,  or  false. 

ovrimos_f  ree_result  <php  4  >=  4  o  3) 

Frees  the  specified  result_id 

int  ovrimos_f ree_result  (int  result_id) 
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ovrimos_free_result()  is  used  to  free  the  result_id. 
ovrimos_free_result()  frees  the  specified  result_id.  Returns  true. 


ovrimos_commit  (php  4  >=  4.0.3) 

Commits  the  transaction 

int  ovrimos_commit  (int  connection_id) 

ovrimos_commit()  is  used  to  commit  the  transaction. 
ovrimos_commit()  commits  the  transaction. 

ovrimos_rollback  (php  4  >=  4.0.3) 

Rolls  back  the  transaction 

int  ovrimos_rollback  (int  connect ion_id) 

ovrimos_rollback()  is  used  to  roll  back  the  transaction. 
ovrimos_rollback()  rolls  back  the  transaction. 
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The  Output  Control  functions  allow  you  to  control  when  output  is  sent  from  the  script.  This  can  be  useful 
in  several  different  situations,  especially  if  you  need  to  send  headers  to  the  browser  after  your  script  has 
began  outputing  data.  The  Output  Control  functions  do  not  affect  headers  sent  using  header;)  or 
setcookie'),  only  functions  such  as  echo')  and  data  between  blocks  of  PHP  code. 


Ejemplo  1.  Output  Control  example 

<?php 

ob_start ( )  ; 
echo  "Hello\n"; 

setcookie  (  " cookiename" ,  "cookiedata"  )  ; 
ob_end_f lush ( )  ; 

?> 


In  the  above  example,  the  output  from  echo ')  would  be  stored  in  the  output  buffer  until  ob_end_flush() 
was  called.  In  the  mean  time,  the  call  to  setcookie')  successfully  stored  a  cookie  without  causing  an 
error.  (You  can  not  normally  send  headers  to  the  browser  after  data  has  already  been  sent.) 

See  also  header ')  and  setcookie')- 
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flush  (PHP  3,  PHP  4  >=  4.0.0) 
Flush  the  output  buffer 

void  flush  () 


Flushes  the  output  buffers  of  PHP  and  whatever  backend  PHP  is  using  (CGI,  a  web  server,  etc.)  This 
effectively  tries  to  push  all  the  output  so  far  to  the  user’s  browser. 


ob_start  (PHP  4  >=4.0.0) 


Turn  on  output  buffering 


void  ob_start  () 


This  function  will  turn  output  buffering  on.  While  output  buffering  is  active  no  output  is  sent  from  the 
script,  instead  the  output  is  stored  in  an  internal  buffer. 

The  contents  of  this  internal  buffer  may  be  copied  into  a  string  variable  using  ob_get_contcnts ').  To 
output  what  is  stored  in  the  internal  buffer,  use  ob  end  tiush  ').  Alternatively,  ob  end  clean ')  will 
silently  discard  the  buffer  contents. 

See  also  ob_get_contents ob_end_flush(),  ob_cnd_clean '),  and  obimplicitflush  ) 


ob_get_contents  (php  4  >=  4.0.0 


Return  the  contents  of  the  output  buffer 


string  ob_get_contents  () 


This  will  return  the  contents  of  the  output  buffer  or  false,  if  output  buffering  isn’t  active. 
See  also  ob_start()  and  ob_get_length '). 


ob_get  Jength  (php  4  >=  4.0.2) 

Return  the  length  of  the  output  buffer 
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string  ob_get_length  () 


This  will  return  the  length  of  the  contents  in  the  output  buffer  or  false,  if  output  buffering  isnt’t  active. 
See  also  ob_start ')  and  ob_get_contents '). 


ob_end_f  lush  (php  4  >=  4.o.o) 

Flush  (send)  the  output  buffer  and  turn  off  output  buffering 

void  ob_end_flush  () 


This  function  will  send  the  contents  of  the  output  buffer  (if  any)  and  turn  output  buffering  off.  If  you 
want  to  further  process  the  buffer’s  contents  you  have  to  call  ob_get_contents()  before  ob_end_flush()  as 
the  buffer  contents  are  discarded  after  ob_get_contents  ')  is  called. 

See  also  ob_start'),  ob_get_contents '),  and  ob  end  clean '). 


ob_end_clean  (php  4  >=  4.o.0) 

Clean  (erase)  the  output  buffer  and  turn  off  output  buffering 

void  ob_end_clean  () 

This  function  discards  the  contents  of  the  output  buffer  and  turns  off  output  buffering. 
See  also  ob_start')  and  ob_end_flush(). 


ob_implicit_flush  {php4>=4.o.o) 

Turn  implicit  flush  on/off 

void  ob_implicit_f lush  ( [int  flag] ) 


ob_implicit_flush()  will  turn  implicit  flushing  on  or  off  (if  no  flag  is  given,  it  defaults  to  on).  Implicit 
flushing  will  result  in  a  flush  operation  after  every  output  call,  so  that  explicit  calls  to  flush ')  will  no 
longer  be  needed. 
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Turning  implicit  flushing  on  will  disable  output  buffering,  the  output  buffers  current  output  will  be  sent 
as  if  ob_end_fiush ')  had  been  called. 

See  also  flush;),  ob_start'),  and  ob_end_fiush '). 
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You  can  use  the  PDF  functions  in  PHP  to  create  PDF  files  if  you  have  the  PDF  library  by  Thomas  Merz 
(available  at  http://www.pdflib.com/pdflib/index.html;  you  will  also  need  the  JPEG  library 
(ftp://ftp.uu.net/graphics/jpeg/)  and  the  TIFF  library  (http://www.libtiff.org/)  to  compile  this.  These  two 
libs  also  quite  often  make  problems  when  configuring  php.  Follow  the  messages  of  configure  to  fix 
possible  problems.  If  you  use  pdflib  2.01  check  how  the  lib  was  installed.  There  should  be  file  or  link 
libpdf.so.  Version  2.01  just  creates  a  lib  with  the  name  libpdf2.01.so  which  cannot  be  found  when  linking 
the  test  programm  in  configure.  You  will  have  to  create  a  symbolic  link  from  libpdf.so  to  libpdf2.01.so.). 

Version  2.20  of  pdflib  has  introduced  more  changes  to  its  API  and  support  for  Chinese  and  japanese 
fonts.  This  unfortunately  causes  some  changes  of  the  pdf  module  of  php4  (not  php3).  If  you  use  pdflib 
2.20  handle  the  in  memory  generation  of  PDF  documents  with  care.  Until  pdflib  3.0  is  released  it  might 
be  unstable.  The  encoding  parameter  of  pdf_set_font  )  has  changed  to  a  string.  This  means  that  instead 
of  e.g.  4  you  have  to  use  ’winansi’. 

If  you  use  pdflib  2.30  the  pdf_set_text_matrix h  will  have  gone.  It  is  not  supported  any  more.  In  general  it 
is  a  good  advise  to  consult  the  release  notes  of  the  used  version  of  pdflib  for  possible  changes. 

Since  version  3.0  of  pdflib  you  should  configure  pdflib  with  the  option  — enable-shared-pdf  lib. 

Any  version  of  PHP4  after  March,  9th  2000  do  not  support  versions  of  pdflib  older  than  3.0.  PHP3  on  the 
other  hand  should  not  be  used  with  version  newer  than  2.01. 

Please  consult  the  excellent  documentation  for  pdflib  shipped  with  the  source  distribution  of  pdflib.  It 
provides  a  very  good  overview  of  what  pdflib  capable  of  doing.  Most  of  the  functions  in  pdflib  and  the 
PHP  module  have  the  same  name.  The  parameters  are  also  identical.  You  should  also  understand  some  of 
the  concepts  of  PDF  or  Postscript  to  efficiently  use  this  module.  All  lengths  and  coordinates  are 
measured  in  Postscript  points.  There  are  generally  72  PostScript  points  to  an  inch,  but  this  depends  on 
the  output  resolution. 

There  is  another  PHP  module  for  pdf  document  creation  based  on  FastlO’s  (http://www.fastio.com/). 
ClibPDF.  It  has  a  slightly  different  API.  Check  the  ClibPDF  functions  section  for  details. 

Currently  all  versions  of  pdflib  are  supported.  It  is  recommended  that  you  use  the  newest  version  since  it 
has  more  features  and  fixes  some  problems  which  required  a  patch  for  the  old  version.  Unfortunately,  the 
changes  of  the  pdflib  API  in  2.x  compared  to  0.6  have  been  so  severe  that  even  some  PHP  functions  had 
to  be  altered.  Here  is  a  list  of  changes: 

•  The  Info  structure  does  not  exist  anymore.  Therefore  the  function  pdf_get_info()  is  obsolete  and  the 
functions  pdf_set_info_creator(),  pdf_set_info_titIe(),  pdf_set_info_author(), 
pdf_set_info_subject()  and  pdf_set_info_keywords()  do  not  take  the  info  structure  as  the  first 
parameter  but  the  pdf  document.  This  also  means  that  the  pdf  document  must  be  opened  before  these 
functions  can  be  called.  The  above  functions  can  and  should  also  be  replaced  by  pdf_set_info() 

•  The  way  a  new  document  is  opened  has  changed.  The  function  pdf_open ')  takes  only  one  parameter 
which  is  the  file  handle  of  a  file  opened  with  fopen '). 

There  were  some  more  changes  with  the  release  2.01  of  pdflib  which  should  be  covered  by  PHP.  Some 
functions  are  not  required  anymore  (e.g.  pdf_put_image()).  You  will  get  a  warning  so  don’t  be  shocked. 

The  pdf  module  introduces  two  new  types  of  variables  (if  pdflib  2.x  is  used  it  is  only  one  new  type).  They 
are  called  pdf  doc  and  pdf  info  (pdf info  is  not  existent  if  pdflib  2.x  is  used,  pdf  doc  is  a  pointer 
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to  a  pdf  document  and  almost  all  functions  need  it  as  its  first  parameter,  pdf  inf  o  contains  meta  data 
about  the  PDF  document.  It  has  to  be  set  before  pdf  open ')  is  called. 

Nota:  The  following  is  only  true  for  pdflib  0.6.  Read  the  pdflib  manual  for  newer  version 


In  order  to  output  text  into  a  PDF  document  you  will  need  to  provide  the  afm  hie  for  each  font.  Afm  hies 
contain  font  metrics  for  a  Postscript  font.  By  default  these  afm  hies  are  searched  for  in  a  directory  named 
'fonts’  relative  to  the  directory  where  the  PHP  script  is  located.  (Again,  this  was  true  for  pdflib  0.6, 
newer  versions  do  not  not  neccessarily  need  the  afm  hies.) 

Most  of  the  functions  are  fairly  easy  to  use.  The  most  difficult  part  is  probably  to  create  a  very  simple  pdf 
document  at  all.  The  following  example  should  help  to  get  started.  It  uses  the  PHP  functions  for  pdflib 
0.6.  It  creates  the  hie  test.pdf  with  one  page.  The  page  contains  the  text  "Times-Roman"  in  an  outlined 
30pt  font.  The  text  is  also  underlined. 

Ejemplo  1.  Creating  a  PDF  document  with  pdflib  0.6 

<?php 

$fp  =  f open ( "test . pdf " ,  "w"); 

$info  =  PDF_get_inf o ( ) ; 

pdf_set_inf o_author ( $inf o,  "Uwe  Steinmann"); 

PDF_set_info_title ( $info,  "Test  for  PHP  wrapper  of  PDFlib  0.6"); 

PDF_set_inf o_author ( $inf o,  "Name  of  Author"); 
pdf_set_inf o_creator ( $inf o,  "See  Author"); 
pdf_set_info_sub ject ($info,  "Testing") ; 

$pdf  =  PDF_open ( $fp,  $info) ; 

PDF_begin_page ( $pdf ,  595,  842); 

PDF_add_outline ($pdf ,  "Page  1"); 
pdf_set_f ont ( $pdf ,  "Times-Roman",  30,  4); 
pdf_set_text_rendering ( $pdf ,  1)  ; 

PDF_show_xy ($pdf ,  "Times  Roman  outlined",  50,  750); 
pdf_moveto ( $pdf ,  50,  740); 
pdf_lineto ( $pdf ,  330,  740); 
pdf_stroke ($pdf) ; 

PDF_end_page ($pdf ) ; 

PDF_close ($pdf ) ; 
fclose ($fp) ; 

echo  "<A  HREF=getpdf . php3>f inished</A>" ; 

?> 


The  PHP  script  getpdf.php3  just  outputs  the  pdf  document. 


<?php 

$fp  =  fopen("test.pdf",  "r"); 

header ( "Content -type :  application/pdf " ) ; 

fpassthru  ($fp) ; 

fclose ($fp) ; 

?> 
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Doing  the  same  with  pdflib  2.x  looks  like  the  following: 


Ejemplo  2.  Creating  a  PDF  document  with  pdflib  2.x 

<?php 

$fp  =  f open ( "test . pdf " ,  "w"); 

$pdf  =  PDF_open ($fp)  ; 

pdf_set_info_author ($pdf ,  "Uwe  Steinmann"); 

PDF_set_info_title ( $pdf ,  "Test  for  PHP  wrapper  of  PDFlib  2.0"); 
PDF_set_inf o_author ( $pdf ,  "Name  of  Author"); 
pdf_set_inf o_creator ( $pdf ,  "See  Author"); 
pdf_set_info_sub ject ($pdf,  "Testing") ; 

PDF_begin_page ( $pdf ,  595,  842); 

PDF_add_outline ($pdf ,  "Page  1"); 
pdf_set_f ont ( $pdf ,  " Times -Roman " ,  30,  4); 

pdf_set_text_rendering ( $pdf ,  1) ; 

PDF_show_xy ($pdf ,  "Times  Roman  outlined",  50,  750); 
pdf_moveto ( $pdf ,  50,  740); 
pdf_lineto ( $pdf ,  330,  740); 
pdf_stroke ($pdf) ; 

PDF_end_page ($pdf ) ; 

PDF_close ($pdf ) ; 
fclose ($fp) ; 

echo  "<A  HREF=getpdf . php3>f inished</A>" ; 

?> 

The  PHP  script  getpdf.php3  is  the  same  as  above. 


The  pdflib  distribution  contains  a  more  complex  example  which  creates  a  serious  of  pages  with  an  analog 
clock.  This  example  converted  into  PHP  using  pdflib  2.x  looks  as  the  following  (you  can  see  the  same 
example  in  the  documentation  for  the  clibpdf  module) 


Ejemplo  3.  pdfclock  example  from  pdflib  2.x  distribution 

<?php 

$pdf filename  =  "clock.pdf"; 

$radius  =  200; 

$margin  =  20; 

$pagecount  =  40; 

$fp  =  fopen ($pdff ilename,  "w"); 

$pdf  =  pdf_open($fp); 

pdf_set_inf o_creator ( $pdf ,  "pdf_clock . php3" ) ; 
pdf_set_inf o_author ( $pdf ,  "Uwe  Steinmann"); 
pdf_set_info_title ( $pdf ,  "Analog  Clock"); 

while ( $pagecount--  >  0)  { 


822 


PDF 


pdf_begin_page ( $pdf ,  2  *  ($radius  +  $margin) ,  2  *  ($radius  +  $margin) )  ; 

pdf_set_transition ( $pdf ,  4);  /*  wipe  */ 

pdf_set_duration ( $pdf ,  0.5); 

pdf_translate ( $pdf ,  $radius  +  $margin,  $radius  +  $margin) ; 
pdf_save ($pdf ) ; 

pdf_setrgbcolor ( $pdf ,  0.0,  0.0,  1.0); 

/*  minute  strokes  */ 
pdf_setlinewidth ($pdf ,  2.0); 

for  ($alpha  =  0;  $alpha  <  360;  $alpha  +=  6)  { 

pdf_rotate ($pdf ,  6.0); 
pdf_moveto ($pdf ,  $radius,  0.0); 
pdf_lineto ( $pdf ,  $radius-$margin/3,  0.0); 
pdf_stroke ($pdf ) ; 

} 

pdf_restore ($pdf ) ; 
pdf_save ($pdf ) ; 

/*  5  minute  strokes  */ 
pdf_setlinewidth ( $pdf ,  3.0); 

for  ($alpha  =  0;  $alpha  <  360;  $alpha  +=  30)  { 

pdf_rotate ($pdf ,  30.0); 
pdf_moveto ( $pdf ,  $radius,  0.0); 
pdf_lineto ( $pdf ,  $radius-$margin,  0.0); 
pdf_stroke ($pdf ) ; 

} 

$ltime  =  getdateO; 

/*  draw  hour  hand  */ 
pdf_save ($pdf ) ; 

pdf_rotate ( $pdf , - ( ( $ltime [ '  minutes' ] / 60 . 0 ) +$ltime [ '  hours'  ]-3.0)*30.0); 

pdf_moveto ($pdf ,  -$radius/10,  -$radius/20 ) ; 

pdf_lineto ($pdf ,  $radius/2,  0.0); 

pdf_lineto ( $pdf ,  -$radius/10,  $radius/20)  ; 

pdf_closepath ($pdf )  ; 

pdf_fill ($pdf)  ; 

pdf_restore ($pdf )  ; 

/*  draw  minute  hand  */ 
pdf_save ($pdf ) ; 

pdf_rotate ( $pdf , - ( ( $ltime ['seconds' ] / 60 . 0 ) +$ltime [ ' minutes' ] — 1 5 . 0 ) *6.0) ; 

pdf_moveto ( $pdf ,  -$radius/10,  -$radius/20 ) ; 

pdf_lineto ($pdf ,  $radius  *  0.8,  0.0); 

pdf_lineto ($pdf ,  -$radius/10,  $radius/20) ; 

pdf_closepath ($pdf ) ; 

pdf_fill ($pdf) ; 

pdf_restore ($pdf ) ; 

/*  draw  second  hand  */ 
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pdf_setrgbcolor ( $pdf ,  1.0,  0.0,  0.0); 

pdf_setlinewidth ( $pdf ,  2); 
pdf_save ($pdf ) ; 

pdf_rotate ( $pdf ,  -( ($ltime [' seconds' ]  - 
pdf_moveto ($pdf ,  -$radius/5,  0.0); 
pdf_lineto ( $pdf ,  $radius,  0.0); 
pdf_stroke ($pdf )  ; 
pdf_restore ($pdf )  ; 

/*  draw  little  circle  at  center  */ 
pdf_circle ( $pdf ,  0,  0,  $radius/30) ; 
pdf_fill ($pdf) ; 

pdf_restore ($pdf ) ; 

pdf_end_page ($pdf ) ; 

} 

$pdf  =  pdf_close ($pdf ) ; 
fclose ($fp) ; 

echo  "<A  HREF=getpdf . php3?f ilename=" . $pdf filename . " >f inished</A> " 
?> 

The  PHP  script  getpdf.php3  just  outputs  the  pdf  document. 

<?php 

$fp  =  fopen ($filename,  "r"); 

header ( "Content-type :  application/pdf " ) ; 

fpassthru  ($fp) ; 

fclose ($fp) ; 


PDF 


PDFget  info  (php 3>=  3.0.6) 

Returns  an  empty  info  structure  for  a  pdf  document 

info  pdf_get_info  (string  filename) 


The  PDF_get_info()  function  returns  an  empty  info  structure  for  the  pdf  document.  It  should  be  filled 
with  appropriate  information  like  the  author,  subject  etc.  of  the  document. 

Nota:  This  functions  is  not  available  if  pdflib  2.x  support  is  activated. 


See  also  PDF_set_info_creator(),  PDF_set_info_author(),  PDF_set_info_keywords(), 
PDF_set_info_title(),  PDF_set_info_subject(). 


PDF  set  info  (php  4) 


Fills  a  field  of  the  document  information 


void  pdf_set_info  (int  pdf  document ,  string  fieldname,  string  value) 


The  PDF_set_info()  function  sets  an  information  field  of  a  pdf  document.  Possible  values  for  the 
fieldname  are  ’Subject’,  ’Title’,  ’Creator’,  ’Author’,  ’Keywords’  and  one  user-defined  name.  It  can  be 
called  before  beginning  a  page. 

Ejemplo  1.  Setting  document  information 

<?php 

$fd  =  f open ( "test . pdf " ,  "w"); 

$pdfdoc  =  pdf_open ( $fd) ; 

pdf_set_inf o ( $pdfdoc,  "Author",  "Uwe  Steinmann"); 
pdf_set_inf o ( $pdf doc,  "Creator",  "Uwe  Steinmann"); 
pdf_set_inf o ( $pdf doc,  "Title",  "Testing  Info  Fields"); 
pdf_set_inf o ( $pdf doc,  "Subject",  "Test"); 
pdf_set_inf o ( $pdf doc,  "Keywords",  "Test,  Fields"); 
pdf_set_inf o ( $pdf doc,  "CustomField" ,  "What  ever  makes  sense") ; 
pdf_begin_page ( $pdf doc,  595,  842); 
pdf_end_page ($pdfdoc)  ; 
pdf_close (Spdfdoc)  ; 

?> 
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Nota:  This  function  replaces  PDF_set_info_keywords(),  PDF  setJnfo_title(), 
PDF_setJnfo_subject(),  PDF_setJnfo_creator(),  PDF_set_info_sybject(). 


PDFopen  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 

Opens  a  new  pdf  document 

int  pdf_open  (int  file,  int  info ) 


The  PDF_open()  function  opens  a  new  pdf  document.  The  corresponding  file  has  to  be  opened  with 
fopen))  and  the  hie  descriptor  passed  as  argument  file,  info  is  the  info  structure  that  has  to  be  created 
with  pdf_get_info').  The  info  structure  will  be  deleted  within  this  function. 

Nota:  The  return  value  is  needed  as  the  first  parameter  in  all  other  functions  writing  to  the  pdf 
document. 


Nota:  This  function  does  not  allow  the  second  parameter  if  pdflib  2.0  support  is  activated. 


See  also  fopen'),  PDF_get_info(),  PDF_close(). 


PDFclose  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 

Closes  a  pdf  document 

void  pdf_close  (int  pdf  document) 


The  PDF_close()  function  closes  the  pdf  document. 

Nota:  Due  to  an  unclean  implementation  of  the  pdflib  0.6  the  internal  closing  of  the  document  also 
closes  the  file.  This  should  not  be  done  because  pdflib  did  not  open  the  file,  but  expects  an  already 
open  file  when  PDF_open()  is  called.  Consequently  it  shouldn’t  close  the  file.  In  order  to  fix  this  just 
take  out  line  190  of  the  file  p_basic.c  in  the  pdflib  0.6  source  distribution  until  the  next  release  of 
pdflib  will  fix  this. 
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Nota:  This  function  works  properly  without  any  patches  to  pdflib  if  pdflib  2.0  support  is  activated. 

See  also  PDF_open(),  fclose'j. 

PDF_begm_page 

(PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 

Starts  new  page 

void  pdf_begin_page  (int  pdf  document ,  double  width,  double  height) 

The  PDF_begin_page()  function  starts  a  new  page  with  height  height  and  width  width.  In  order  to 
create  a  valid  document  you  must  call  this  function  and  PDF_end_page(). 

See  also  PDF_end_page(). 

PDF_end_page  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 

Ends  a  page 

void  pdf  end  page  (int  pdf  document) 

The  PDF_end_page()  function  ends  a  page.  Once  a  page  is  ended  it  cannot  be  modified  anymore. 

See  also  PDF_begin_page(). 


PDFshow  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 

Output  text  at  current  position 

void  pdf_show  (int  pdf  document ,  string  text) 

The  PDF_show()  function  outputs  the  string  text  at  the  current  position  using  the  current  font. 
See  also  PDF_show_xy(),  PDF_set_text_pos(),  PDF_set_font(). 


827 


PDF 


PDFshowboxed  (php  4  >=  4.0.0) 


Output  text  in  a  box 


int  pdf_show_boxed  (int  pdf  document ,  string  text,  double  x-coor,  double 
y-coor,  double  width,  double  height,  string  mode) 


The  PDF_show_boxed( )  function  outputs  the  string  text  in  a  box  with  its  lower  left  position  at 
(x-coor,  y-coor).  The  boxes  dimension  is  height  by  width.  The  parameter  mode  determines 
how  the  text  is  type  set.  If  width  and  height  are  zero,  the  mode  can  be  "left",  "right"  or  "center".  If 
width  or  height  is  unequal  zero  it  can  also  be  "justify"  and  "fulljustify". 

Returns  the  number  of  characters  that  could  not  be  processed  because  they  did  not  fit  into  the  box. 

See  also  PDF_show(),  PDF_show_xy(). 


PDFshowxy  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 

Output  text  at  given  position 

void  pdf_show_xy  (int  pdf  document ,  string  text,  double  x-coor,  double 
y-coor) 


The  PDF_show_xy()  function  outputs  the  string  text  at  position  (x-coor,  y-coor). 
See  also  PDF_show(). 


PDF  set  font  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 


Selects  a  font  face  and  size 

void  pdf_set_font  (int  pdf  document ,  string  font  name,  double  size,  string 
encoding  [,  int  embed]) 


The  PDF_set_font()  function  sets  the  current  font  face,  font  size  and  encoding.  If  you  use  pdflib  0.6  you 
will  need  to  provide  the  Adobe  Font  Metrics  (afm-files)  for  the  font  in  the  font  path  (default  is  ./fonts).  If 
you  use  php3  or  a  version  of  pdflib  older  than  2.20  the  fourth  parameter  encoding  can  take  the 
following  values:  0  =  builtin,  1  =  pdfdoc,  2  =  macroman,  3  =  macexpert,  4  =  winansi.  An  encoding 
greater  than  4  and  less  than  0  will  default  to  winansi.  winansi  is  often  a  good  choice.  If  you  use  php4  and 
a  version  of  pdflib  >=  2.20  the  encoding  parameter  has  changed  to  a  string.  Use  ’winansi’,  ’builtin’. 
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’host’,  ’macroman’  etc.  instead.  If  the  last  parameter  is  set  to  1  the  font  is  embedded  into  the  pdf 
document  otherwise  it  is  not.  To  embed  a  font  is  usually  a  good  idea  if  the  font  is  not  widely  spread  and 
you  cannot  ensure  that  the  person  watching  your  document  has  access  on  fonts  in  the  document.  I  font  is 
only  embedded  once  even  if  you  call  PDF_set_font()  several  times. 

Nota:  This  function  has  to  be  called  after  PDF_begin_page()  in  order  to  create  a  valid  pdf  document. 


Nota:  If  you  reference  a  font  in  a  .upr  file  make  sure  the  name  in  the  atm  file  and  the  font  name  are 
the  same.  Otherwise,  the  font  will  be  embedded  several  times  (Thanks  to  Paul  Haddon  for  finding 
this.) 


PDF_set_leading  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 


Sets  distance  between  text  lines 


void  pdf_set_leading  (int  pdf  document ,  double  distance) 


The  PDF_set_leading()  function  sets  the  distance  between  text  lines.  This  will  be  used  if  text  is  output 

by  PDF_continue_text(). 

See  also  PDF_continue_text(). 


PDF_set_parameter  (php  4  >=  4.0.0 


Sets  certain  parameters 


void  pdf  set  parameter  (int  pdf  document ,  string  name,  string  value) 


The  PDF_set_parameter()  function  sets  several  parameters  of  pdflib  which  are  of  the  type  string. 
See  also  PDF_get_value(),  PDF_set_value(),  PDF_get_parameter(). 


PDF_get_parameter  (php  4  > 


Gets  certain  parameters 
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string  pdf  get  parameter  (int  pdf  document ,  string  name,  double  modifier) 


The  PDF_get_parameter()  function  gets  several  parameters  of  pdflib  which  are  of  the  type  string.  The 
function  parameter  modifier  characterizes  the  parameter  to  get.  If  the  modifier  is  not  needed  it  has  to 
be  0. 

See  also  PDF_get_value(),  PDF_set_vaIue(),  PDF_set_parameter(). 


PDF_set_value  (php  4  > 


Sets  certain  numerical  value 


void  pdf_set_value  (int  pdf  document ,  string  name, 


double  value) 


The  PDF_set_value()  function  sets  several  numerical  parameters  of  pdflib. 
See  also  PDF_get_value(),  PDF_get_parameter(),  PDF_set_parameter(). 


PDF_get_value  (php  4  > 


Gets  certain  numerical  value 


double  pdf_get_value  (int  pdf  document ,  string  name,  double  modifier) 


The  PDF_get_value()  function  gets  several  numerical  parameters  of  pdflib.  The  function  parameter 
modifier  characterizes  the  parameter  to  get.  If  the  modifier  is  not  needed  it  has  to  be  0. 

See  also  PDF_set_value(),  PDF_get_parameter(),  PDF_set_parameter(). 


PDF_set_text_rendering  (php  3>=  3.0.6,  php  4  >=  4 .0  .o> 


Determines  how  text  is  rendered 


void  pdf_set_text_rendering  (int  pdf  document ,  int  mode) 


The  PDF_set_text_rendering()  function  determines  how  text  is  rendered.  The  possible  values  for  mode 
are  0=fill  text,  l=stroke  text,  2=fill  and  stroke  text,  3=invisible,  4=fill  text  and  add  it  to  cliping  path. 
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5=stroke  text  and  add  it  to  clipping  path,  6=fill  and  stroke  text  and  add  it  to  cliping  path,  7=add  it  to 
clipping  path. 


PDF_set_horiz_scaling  (php  3>=  3.0.6,  php  4  >=  4  0  0) 

Sets  horizontal  scaling  of  text 

void  pdf_set_horiz_scaling  (int  pdf  document ,  double  scale) 


The  PDF_set_horiz_scaling()  function  sets  the  horizontal  scaling  to  scale  percent. 


PDF_set_text_rise  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 

Sets  the  text  rise 

void  pdf_set_text_rise  (int  pdf  document ,  double  rise) 


The  PDF_set_text_rise()  function  sets  the  text  rising  to  rise  points. 


PDF_set_text_matrix  (php  3>=  3.0.6) 

Sets  the  text  matrix 

void  pdf_set_text_matrix  (int  pdf  document ,  array  matrix) 


The  PDF_set_text_matrix()  function  sets  a  matrix  which  describes  a  transformation  applied  on  the 
current  text  font.  The  matrix  has  to  passed  as  an  array  with  six  elements. 


P  D  F_set_text_pos  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 

Sets  text  position 

void  pdf_set_text_pos  (int  pdf  document ,  double  x-coor,  double  y-coor) 
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The  PDF_set_text_pos()  function  sets  the  position  of  text  for  the  next  pdf_show ')  function  call. 
See  also  PDF_show(),  PDF_show_xy(). 


PDF_set_char_spacing  (php  3>=  3.0.6,  php  4  >=  4.0.0 

Sets  character  spacing 

void  pdf_set_char_spacing  (int  pdf  document,  double  space) 


The  PDF_set_char_spacing()  function  sets  the  spacing  between  characters. 
See  also  PDF_set_word_spacing(),  PDF_set_leading(). 


PDF_set_word_spacing  (php 3>=  3.0.6,  php 4 >=  4.o.o 


Sets  spacing  between  words 


void  pdf_set_word_spacing  (int  pdf  document ,  double  space) 


The  PDF_set_word_spacing()  function  sets  the  spacing  between  words. 
See  also  PDF_set_char_spacing(),  PDF_set_leading(). 


PDFskew  (php  4  >=  4.0.0) 

Skews  the  coordinate  system 

void  pdf_skew  (int  pdf  document ,  double  alpha,  double  beta) 


The  PDF_skew()  function  skew  the  coordinate  system  by  alpha  (x)  and  beta  (y)  degrees,  alpha  and 
beta  may  not  be  90  or  270  degrees. 
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PDF_continue_text  (php  3>=  3.0.6,  php  4  >=  4.0.o) 

Outputs  text  in  next  line 

void  pdf_continue_text  (int  pdf  document ,  string  text) 

The  PDF_continue_text()  function  outputs  the  string  in  text  in  the  next  line.  The  distance  between  the 
lines  can  be  set  with  PDF_set_leading(). 

See  also  PDF_show_xy(),  PDF_set_leading(),  PDF_set_text_pos(). 

PDFstringwidth  (php  3>=  3.0.e,  php  4  >=  4  0  o> 

Returns  width  of  text  using  current  font 

double  pdf_stringwidth  (int  pdf  document ,  string  text) 

The  PDF_stringwidth()  function  returns  the  width  of  the  string  in  text  by  using  the  current  font.  It 
requires  a  font  to  be  set  before  with  PDF_set_font(). 

See  also  PDF_set_font(). 


PDFsave  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 


Saves  the  current  environment 


void  pdf_save  (int  pdf  document) 


The  PDF_save()  function  saves  the  current  environment.  It  works  like  the  postscript  command  gsave. 
Very  useful  if  you  want  to  translate  or  rotate  an  object  without  effecting  other  objects.  PDF_save() 
should  always  be  followed  by  PDF_restore()  to  restore  the  environment  before  PDF_save(). 

See  also  PDF_restore(). 


PDFrestore  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 

Restores  formerly  saved  environment 
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void  pdf_restore  (int  pdf  document) 


The  PDF_restore()  function  restores  the  environment  saved  with  PDF_save().  It  works  like  the 
postscript  command  grestore. 

Ejemplo  1.  Save  and  Restore 

<?php  PDF_save ( $pdf )  ; 

//  do  all  kinds  of  rotations,  transformations,  ... 

PDF_restore ($pdf )  ?> 


See  also  PDF_save(). 


PDFtranslate  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 


Sets  origin  of  coordinate  system 


void  pdf_translate  (int  pdf  document ,  double  x-coor,  double  y-coor) 


The  PDF_translate()  function  sets  the  origin  of  coordinate  system  to  the  point  ( x-coor ,  y-coor) 
relativ  the  current  origin.  The  following  example  draws  a  line  from  (0,  0)  to  (200,  200)  relative  to  the 
initial  coordinate  system.  You  have  to  set  the  current  point  after  PDF_translate()  and  before  you  start 
drawing  more  objects. 

Ejemplo  1.  Translation 

<?php  PDF_moveto ($pdf ,  0,  0); 

PDF_lineto ( $pdf ,  100,  100); 

PDF_stroke ($pdf) ; 

PDF_translate ( $pdf ,  100,  100); 

PDF_moveto ( $pdf ,  0,  0); 

PDF_lineto ( $pdf ,  100,  100); 

PDF_stroke ($pdf) ; 

?> 


PDF  scale  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 


Sets  scaling 
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void  pdf_scale  (int  pdf  document,  double  x-scale,  double  y-scale) 


The  PDF_scale()  function  sets  the  scaling  factor  in  both  directions.  The  following  example  scales  x  and 
y  direction  by  72.  The  following  line  will  therefore  be  drawn  one  inch  in  both  directions. 

Ejemplo  1.  Scaling 

<?php  PDF_scale ( $pdf ,  72.0,  72.0); 

PDF_lineto ( $pdf ,  1,  1); 

PDF_stroke ($pdf) ; 

?> 


PDF_rotate  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 

Sets  rotation 

void  pdf_rotate  (int  pdf  document ,  double  angle) 


The  PDF_rotate()  function  sets  the  rotation  in  degress  to  angle. 


PDFsetflat  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 

Sets  flatness 

void  pdf_setflat  (int  pdf  document ,  double  value ) 


The  PDF_setflat()  function  sets  the  flatness  to  a  value  between  0  and  100. 


PDFsetlinejoin  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 

Sets  linejoin  parameter 

void  pdf_setline join  (int  pdf  document ,  long  value) 
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The  PDF_setlinejoin()  function  sets  the  linejoin  parameter  between  a  value  of  0  and  2. 


PDF_setlinecap  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 

Sets  linecap  parameter 

void  pdf_setlinecap  (int  pdf  document ,  int  value ) 


The  PDF_setlinecap()  function  sets  the  linecap  parameter  between  a  value  of  0  and  2. 


PDFsetmiterlimit  (php  3>=  3.0.6,  php  4  >=  4.0.0) 

Sets  miter  limit 

void  pdf_setmiterlimit  (int  pdf  document ,  double  value) 


The  PDF_setmiterlimit()  function  sets  the  miter  limit  to  a  value  greater  of  equal  than  1 . 


PDF_setlinewidth  (php3>=  3.0.6,  php4>=  4.0.0) 

Sets  line  width 

void  pdf_setlinewidth  (int  pdf  document ,  double  width) 


The  PDF_setlinewidth()  function  sets  the  line  width  to  width. 


PDFsetdash  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 

Sets  dash  pattern 

void  pdf_setdash  (int  pdf  document ,  double  white,  double  black) 
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The  PDF_setdash()  function  sets  the  dash  pattern  white  white  points  and  black  black  points.  If  both 
are  0  a  solid  line  is  set. 


PDFmoveto  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 

Sets  current  point 

void  pdf_moveto  (int  pdf  document ,  double  x-coor,  double  y-coor) 


The  PDF_moveto()  function  sets  the  current  point  to  the  coordinates  x-coor  and  y-coor. 


PDFcurveto  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 


Draws  a  curve 


void  pdf_curveto  (int  pdf  document ,  double  xl, 
y2,  double  x3,  double  y3 ) 


double  yl,  double  x2, 


double 


The  PDF_curveto()  function  draws  a  Bezier  curve  from  the  current  point  to  the  point  ( x3 ,  y3 )  using 
(xl,  yl)  and  (x2,  y2 )  as  control  points. 

See  also  PDF_moveto(),  PDF_lineto(),  PDF_stroke(). 


PDF  lineto  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 


Draws  a  line 


void  pdf_lineto  (int  pdf  document , 


double  x-coor, 


double  y-coor) 


The  PDF_lineto()  function  draws  a  line  from  the  current  point  to  the  point  with  coordinates  ( x-coor , 
y-coor). 

See  also  PDF_moveto(),  PDF_curveto(),  PDF_stroke(). 
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PDF  circle  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 


Draws  a  circle 


void  pdf_circle  (int  pdf  document ,  double  x-coor,  double  y-coor,  double 
radius) 


The  PDF_circle()  function  draws  a  circle  with  center  at  point  (x-coor,  y-coor)  and  radius  radius. 
See  also  PDF_arc(),  PDF_stroke(). 


PDF  arc 


(PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 


Draws  an  arc 


void  pdf_arc  (int  pdf  document ,  double  x-coor,  double  y-coor,  double  radius, 
double  start,  double  end) 


The  PDF_arc()  function  draws  an  arc  with  center  at  point  ( x-coor ,  y-coor)  and  radius  radius, 
starting  at  angle  start  and  ending  at  angle  end. 

See  also  PDF_circle(),  PDF_stroke(). 


PDF  rect 


(PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 


Draws  a  rectangle 


void  pdf_rect  (int  pdf  document ,  double  x-coor,  double  y-coor,  double  width, 
double  height) 


The  PDF_rect()  function  draws  a  rectangle  with  its  lower  left  corner  at  point  (x-coor,  y-coor).  This 
width  is  set  to  widgth.  This  height  is  set  to  height. 

See  also  PDF_stroke(). 


PDF_closepath  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 


Closes  path 
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void  pdf_closepath  (int  pdf  document) 


The  PDF_closepath()  function  closes  the  current  path.  This  means,  it  draws  a  line  from  current  point  to 
the  point  where  the  first  line  was  started.  Many  functions  like  PDF_moveto(),  PDF_circle()  and 
PDF_rect()  start  a  new  path. 


PDFstroke  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 


Draws  line  along  path 


void  pdf_stroke  (int  pdf  document) 


The  PDF_stroke()  function  draws  a  line  along  current  path.  The  current  path  is  the  sum  of  all  line 
drawing.  Without  this  function  the  line  would  not  be  drawn. 

See  also  PDF_closepath( ),  PDF_closepath_stroke(). 


PDF  closepath  stroke  (php 3>=  3.o.6,  php 4 >=  4.0.0 


Closes  path  and  draws  line  along  path 


void  pdf_closepath_stroke  (int  pdf  document) 


The  PDF_closepath_stroke()  function  is  a  combination  of  PDF_closepath( )  and  PDF_stroke().  It  also 
clears  the  path. 

See  also  PDF_closepath(),  PDF_stroke(). 


PDF  fill 


(PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 


Fills  current  path 


void  pdf_fill  (int  pdf  document) 


The  PDF_fill()  function  fills  the  interior  of  the  current  path  with  the  current  fill  color. 
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See  also  PDF_closepath(),  PDF_stroke(),  PDF_setgray_fill(),  PDF_setgray(), 
PDF_setrgbcolor_fill(),  PDF_setrgbcolor(). 


PDF_f ill  stroke  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 


Fills  and  strokes  current  path 


void  pdf_f ill_stroke  (int  pdf  document) 


The  PDF_fill_stroke()  function  fills  the  interior  of  the  current  path  with  the  current  fill  color  and  draws 
current  path. 

See  also  PDF_closepath( ),  PDF_stroke(),  PDF_fill(),  PDF_setgray_fill(),  PDF_setgray(), 
PDF_setrgbcolor_fill(),  PDF_setrgbcolor(). 


PDFclosepathf  illstroke  (php  3>=  3.0.6,  php  4  >=  4  0  o> 


Closes,  fills  and  strokes  current  path 


void  pdf_closepath_fill_stroke  (int  pdf  document) 


The  PDF_closepath_fill_stroke()  function  closes,  fills  the  interior  of  the  current  path  with  the  current 
fill  color  and  draws  current  path. 

See  also  PDF_closepath(),  PDF_stroke(),  PDF_fill(),  PDF_setgray_fill(),  PDF_setgray(), 
PDF_setrgbcolor_fill(),  PDF_setrgbcolor(). 


PDFendpath  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 

Ends  current  path 

void  pdf_endpath  (int  pdf  document ) 

The  PDF_endpath()  function  ends  the  current  path  but  does  not  close  it. 
See  also  PDF_closepath(). 
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PDFclip  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 

Clips  to  current  path 

void  pdf_clip  (int  pdf  document) 

The  PDF_clip()  function  clips  all  drawing  to  the  current  path. 

PDF_setgray_fill  (php3>=  3.0.6,  php4>=  4.0.0) 

Sets  filling  color  to  gray  value 

void  pdf_setgray_f ill  (int  pdf  document ,  double  gray  value) 

The  PDF_setgray_fill()  function  sets  the  current  gray  value  to  fill  a  path. 

See  also  PDF_setrgbcolor_fill(). 

PDF_setgray_stroke  <php  3>=  3.0.6,  php  4  >=  4.0.0) 

Sets  drawing  color  to  gray  value 

void  pdf_setgray_stroke  (int  pdf  document ,  double  gray  value) 

The  PDF_setgray_stroke()  function  sets  the  current  drawing  color  to  the  given  gray  value. 
See  also  PDF_setrgbcolor_stroke(). 

PDF_setgray  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 

Sets  drawing  and  filling  color  to  gray  value 

void  pdf_setgray  (int  pdf  document,  double  gray  value) 

The  PDF_setgray()  function  sets  the  current  drawing  and  filling  color  to  the  given  gray  value. 
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See  also  PDF_setrgbcolor_stroke(),  PDF_setrgbcolor_fill(). 


PDFsetrgbcolorf  ill  (php  3>=  3.0.6,  php  4  >=  4.0.0 


Sets  filling  color  to  rgb  color  value 


void  pdf_setrgbcolor_f ill  (int  pdf  document ,  double  red  value,  double  green 
value,  double  blue  value ) 


The  PDF_setrgbcolor_fill()  function  sets  the  current  rgb  color  value  to  fill  a  path. 
See  also  PDF_setrgbcolor_fill(). 


PDFsetrgbcolorstroke  (php  3>=  3.0.6,  php  4  >=  4 .0 .0 


Sets  drawing  color  to  rgb  color  value 


void  pdf_setrgbcolor_stroke  (int  pdf  document ,  double  red  value,  double  green 
value,  double  blue  value) 


The  PDF_setrgbcolor_stroke()  function  sets  the  current  drawing  color  to  the  given  rgb  color  value. 
See  also  PDF_setrgbcolor_stroke(). 


PDF  setrgbcolor  (php  3>=  3  0  6  php 4 >=  4.0.o) 


Sets  drawing  and  filling  color  to  rgb  color  value 


void  pdf_setrgbcolor  (int  pdf  document ,  double  red  value,  double  green  value, 
double  blue  value) 


The  PDF_setrgbcolor_stroke()  function  sets  the  current  drawing  and  filling  color  to  the  given  rgb  color 
value. 

See  also  PDF_setrgbcolor_stroke(),  PDF_setrgbcolor_fill(). 


842 


PDF 


PDF_add_outline  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 


Adds  bookmark  for  current  page 


int  pdf_add_outline  (int  pdf  document,  string  text  [,  int  parent  [,  int 
open ] ] ) 


The  PDF_add_outline()  function  adds  a  bookmark  with  text  text  that  points  to  the  current  page.  The 
bookmark  is  inserted  as  a  child  of  parent  and  is  by  default  open  if  open  is  not  0.  The  return  value  is 
an  identifier  for  the  bookmark  which  can  be  used  as  a  parent  for  other  bookmarks.  Therefore  you  can 
build  up  hierarchies  of  bookmarks. 

Unfortunately  pdflib  does  not  make  a  copy  of  the  string,  which  forces  PHP  to  allocate  the  memory. 
Currently  this  piece  of  memory  is  not  been  freed  by  any  PDF  function  but  it  will  be  taken  care  of  by  the 
PHP  memory  manager. 


PDF_set_transition  (php 3>=  3 o 6  php 4 >=  4.0.0) 


Sets  transition  between  pages 


void  pdf_set_transition  (int  pdf  document ,  int  transition) 


The  PDF_set_transition()  function  set  the  transition  between  following  pages.  The  value  of 

transition  can  be 

0  for  none, 

1  for  two  lines  sweeping  across  the  screen  reveal  the  page, 

2  for  multiple  lines  sweeping  across  the  screen  reveal  the  page, 

3  for  a  box  reveals  the  page, 

4  for  a  single  line  sweeping  across  the  screen  reveals  the  page, 

5  for  the  old  page  dissolves  to  reveal  the  page, 

6  for  the  dissolve  effect  moves  from  one  screen  edge  to  another, 

7  for  the  old  page  is  simply  replaced  by  the  new  page  (default) 

See  also  PDF_set_duration(). 


PDF_set_duration  (php  3>=  3.0.6,  php  4  >=  4.0.0) 


Sets  duration  between  pages 


void  pdf_set_duration  (int  pdf  document ,  double  duration) 


843 


PDF 


The  PDF_set_duration()  function  set  the  duration  between  following  pages  in  seconds. 
See  also  PDF_set_transition(). 


PDF_open_gif 


(PHP  3>=  3.0.7,  PHP  4  >=  4.0.0) 


Opens  a  GIF  image 


int  pdf_open_gif  (int  pdf  document ,  string  filename) 


The  PDF_open_gif()  function  opens  an  image  stored  in  the  file  with  the  name  filename.  The  format 
of  the  image  has  to  be  gif.  The  function  returns  a  pdf  image  identifier. 

Ejemplo  1.  Including  a  gif  image 

<?php 

$im  =  PDF_open_gif ( $pdf ,  "test.gif"); 
pdf_place_image ( $pdf ,  $im,  100,  100,  1); 
pdf_close_image ($pdf,  $im) ; 

?> 


See  also  PDF_close_image(),  PI) F  ope n  j peg(),  PDF_open_memory_image(), 
PDF_execute_image(),  PDF_place_image(),  PDF_put_image(). 


PDFopenpng  (php  4  >=  4 .0 .0) 


Opens  a  PNG  image 


int  pdf  open  png  (int  pdf,  string  png_file) 


The  PDF_open_png()  function  opens  an  image  stored  in  the  file  with  the  name  filename.  The  format 
of  the  image  has  to  be  png.  The  function  returns  a  pdf  image  identifier. 

Ejemplo  1.  Including  a  PNG  image 


<?php 

$im  =  PDF  open  png  ($pdf,  "test. png"); 
pdf_place_image  ($pdf,  $im,  100,  100,  1)  ; 
pdf_close_image  ($pdf,  $im) ; 

?> 
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See  also  PDF_close_image(),  PDF_open  _jpeg(),  PDF_open_gif(),  PDF_open_memory_image(), 
PDF_execute_image(),  PDF_place_image(),  PDF_put_image(). 


PDF  open  memory Jmage  (php 3>=  3.0.10,  php 4 >=  4.0.0 


Opens  an  image  created  with  PHP’s  image  functions 


int  pdf_open_memory_image  (int  pdf  document ,  int  image) 


The  PDF_open_memory_image()  function  takes  an  image  created  with  the  PHP’s  image  functions  and 
makes  it  available  for  the  pdf  document.  The  function  returns  a  pdf  image  identifier. 

Ejemplo  1.  Including  a  memory  image 

<?php 

$im  =  ImageCreate ( 100 ,  100); 

$col  =  ImageColorAllocate ( $im,  80,  45,  190); 

ImageFill ($im,  10,  10,  $col) ; 

$pim  =  PDF_open_memory_image ( $pdf ,  $im) ; 

ImageDestroy ($im) ; 

pdf_place_image ( $pdf ,  $pira,  100,  100,  1); 
pdf_close_image ($pdf,  $pira) ; 

?> 


See  also  PDF_close_image(),  PDF_open  jpeg(),  PDF_open_gif(),  PDF_open_png() 
PDF_execute_image(),  PDF_place_image(),  PDF_put_image(). 


PDF_openJpeg  (PHP  3>=  3.0.7,  PHP  4  >=  4.0.0) 


Opens  a  JPEG  image 


int  pdf_open_jpeg  (int  pdf  document ,  string  filename) 


The  PDF_open  jpeg()  function  opens  an  image  stored  in  the  file  with  the  name  filename.  The  format 
of  the  image  has  to  be  jpeg.  The  function  returns  a  pdf  image  identifier. 

See  also  PDF_close_image(),  PDF_open_gif(),  PDF_open_png(),  PDF_open_memory_image(), 
PDF_execute_image(),  PDF_place_image(),  PDF_put_image(). 
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PDFcloseJmage  (PHP  3>=  3.0.7,  PHP  4  >=  4.0.0) 


Closes  an  image 


void  pdf_close_image  (int  image) 


The  PDF_close_image()  function  closes  an  image  which  has  been  opened  with  any  of  the 
PDF_open_xxx()  functions. 

See  also  PDF_open  _jpeg(),  PDF_open_gif(),  PDF_open_memory_image(). 


PDF_place_image  (PHP  3>=  3.0.7,  PHP  4  >=  4.0.0) 


Places  an  image  on  the  page 


void  pdf_place_image  (int  pdf  document ,  int  image,  double  x-coor,  double 
y-coor,  double  scale) 


The  PDF_place_image()  function  places  an  image  on  the  page  at  postion  (x-coor,  x-coor).  The 
image  can  be  scaled  at  the  same  time. 

See  also  PDF_put_image(). 


PDF_put  Jmage  (php  3>=  3.0.7) 


Stores  an  image  in  the  PDF  for  later  use 


void  pdf_put_image  (int  pdf  document ,  int  image) 


The  PDF_put_image()  function  places  an  image  in  the  PDF  file  without  showing  it.  The  stored  image 
can  be  displayed  with  the  PDF_execute_image()  function  as  many  times  as  needed.  This  is  useful  when 
using  the  same  image  multiple  times  in  order  to  keep  the  file  size  small.  Using  PDF_put_image()  and 
PDF_execute_image()  is  highly  recommended  for  larger  images  (several  kb)  if  they  show  up  more  than 
once  in  the  document. 

Nota:  This  function  has  become  meaningless  with  version  2.01  of  pdflib.  It  will  just  output  a  warning. 
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See  also  PDF_put_image(),  PDF_place_image(),  PDF_execute_image(). 


PDF_execute  Jmage  (php  3>=  3.0.7) 


Places  a  stored  image  on  the  page 


void  pdf_execute_image  (int  pdf  document ,  int  image,  double  x-coor,  double 
y-coor,  double  scale) 


The  PDF_execute_image()  function  displays  an  image  that  has  been  put  in  the  PDF  file  with  the 
PDF_put_image()  function  on  the  current  page  at  the  given  coordinates. 

The  image  can  be  scaled  while  displaying  it.  A  scale  of  1.0  will  show  the  image  in  the  original  size. 

Nota:  This  function  has  become  meaningless  with  version  2.01  of  pdflib.  It  will  just  output  a  warning. 


Ejemplo  1.  Multiple  show  of  an  image 

<?php 

$im  =  ImageCreate ( 100 ,  100); 

$coll  =  ImageColorAllocate ($im,  80,  45,  190); 
ImageFill ($im,  10,  10,  $coll); 

$pim  =  PDF_open_memory_image ( $pdf ,  $im) ; 
pdf_put_image ( $pdf ,  $pim) ; 

pdf_execute_image ( $pdf ,  $pim,  100,  100,  1); 
pdf_execute_image ( $pdf ,  $pim,  200,  200,  2); 
pdf_close_image ($pdf,  $pim) ; 

?> 


pdf_add_annotation  (PHP  3>=  3.0.12,  PHP  4  >=  4.0.0) 


Adds  annotation 


void  pdf_add_annotation  (int  pdf  document ,  double  llx,  double  lly,  double 
urx,  double  ury ,  string  title,  string  content) 
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The  pdf_add_annotation()  adds  a  note  with  the  lower  left  comer  at  ( llx ,  1  ly)  and  the  upper  right 
corner  at  ( urx ,  ury). 


PDF_set_border_style  (PHp  3>=  3.0.i2,  php  4  >=  4.0.0) 

Sets  style  of  border  around  links  and  annotations 

void  pdf_set_border_style  (int  pdf  document ,  string  style,  double  width) 

The  PDF_set_border_style()  function  sets  the  style  and  width  of  the  suroundig  box  of  links  and 
annotations.  The  parameter  style  can  be  ’solid’  or  ’dashed’. 

See  also  PDF_set_border_color(),  PDF_set_border_dash(). 


PDF_set_border_color  (php  3>=  3012,  php  4  >=  4.0.0) 

Sets  color  of  border  around  links  and  annotations 

void  pdf_set_border_color  (int  pdf  document ,  double  red,  double  green,  double 
blue) 


The  PDF_set_border_color()  function  sets  the  color  of  the  suroundig  box  of  links  and  annotations.  The 
three  color  components  have  to  have  a  value  between  0.0  and  1.0. 

See  also  PDF_set_border_style(),  PDF_set_border_dash(). 


PDF_set_border_dash  (PHP4) 


Sets  dash  style  of  border  around  links  and  annotations 


void  pdf_set_border_dash  (int  pdf  document ,  double  black, 


double  white) 


The  PDF_set_border_dash()  function  sets  the  lenght  of  black  and  white  areas  of  a  dashed  line  of  the 
suroundig  box  of  links  and  annotations. 

See  also  PDF_set_border_style(),  PDF_set_border_color(). 
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LXIV.  Verisign  Payflow  Pro  functions 

This  extension  allows  you  to  process  credit  cards  and  other  financial  transactions  using  Verisign  Payment 
Services,  formerly  known  as  Signio  (http://www.verisign.com/payment/). 

These  functions  are  only  available  if  PHP  has  been  compiled  with  the  — with-pfpro  [=dir]  option. 
You  will  require  the  appropriate  SDK  for  your  platform,  which  may  be  downloaded  from  within  the 
manager  interface  (https://testmanager.signio.com/Downloads/Downloads_secure.htm)  once  you  have 
registered. 

Once  you  have  downloaded  the  SDK  you  should  copy  the  files  from  the  lib  directory  of  the  distribution. 
Copy  the  header  file  pfpro .  h  to  /usr/local/include  and  the  library  hie  libpfpro .  so  to 
/ us r/ local /lib. 

When  using  these  functions,  you  may  omit  calls  to  pfpro_init')  and  pfpro  cleanup')  as  this  extension 
will  do  so  automatically  if  required.  However  the  functions  are  still  available  in  case  you  are  processing  a 
number  of  transactions  and  require  fine  control  over  the  library.  You  may  perform  any  number  of 
transactions  using  pfpro_process ')  between  the  two. 

These  functions  have  been  added  in  PHP  4.0.2. 

Nota:  These  functions  only  provide  a  link  to  Verisign  Payment  Services.  Be  sure  to  read  the  Payflow 
Pro  Developers  Guide  for  full  details  of  the  required  parameters. 
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pfpro_init(PHP4>=4  0  2) 


Verisign  Payflow  Pro 


Initialises  the  Payflow  Pro  library 


void  pfpro_init  () 


pfpro_init()  is  used  to  initialise  the  Payflow  Pro  library.  You  may  omit  this  call,  in  which  case  this 
extension  will  automatically  call  pfpro_init()  before  the  first  transaction. 

See  also  pfpro_cleanupO- 


pf  pro_cleanup  <php  4  >=  4 .0 ,2) 


Shuts  down  the  Payflow  Pro  library 


void  pfpro_cleanup  () 


pfpro_cleanup()  is  used  to  shutdown  the  Payflow  Pro  library  cleanly.  It  should  be  called  after  you  have 
processed  any  transactions  and  before  the  end  of  your  script.  However  you  may  omit  this  call,  in  which 
case  this  extension  will  automatically  call  pfpro_cleanup()  after  your  script  terminates. 

See  also  pfpm  init'j. 


pf pro_process  php  4  >=  4.0.2) 


Process  a  transaction  with  Payflow  Pro 


array  pfpro_process  (array  parameters  [,  string  address  [,  int  port  [,  int 
timeout  [,  string  proxy  address  [,  int  proxy  port  [,  string  proxy  logon  [, 
string  proxy  password ] ]]]]]]) 


Returns:  An  associative  array  containing  the  response 

pfpro_process()  processes  a  transaction  with  Payflow  Pro.  The  first  parameter  is  an  associative  array 
containing  keys  and  values  that  will  be  encoded  and  passed  to  the  processor. 

The  second  parameter  is  optional  and  specifies  the  host  to  connect  to.  By  default  this  is  "test.signio.com", 
so  you  will  certainly  want  to  change  this  to  "connect.signio.com"  in  order  to  process  live  transactions. 

The  third  parameter  specifies  the  port  to  connect  on.  It  defaults  to  443,  the  standard  SSL  port. 


850 


Verisign  Payflow  Pro 


The  fourth  parameter  specifies  the  timeout  to  be  used,  in  seconds.  This  defaults  to  30  seconds.  Note  that 
this  timeout  appears  to  only  begin  once  a  link  to  the  processor  has  been  established  and  so  your  script 
could  potentially  continue  for  a  very  long  time  in  the  event  of  DNS  or  network  problems. 

The  fifth  parameter,  if  required,  specifies  the  hostname  of  your  SSL  proxy.  The  sixth  parameter  specifies 
the  port  to  use. 

The  seventh  and  eighth  parameters  specify  the  logon  identity  and  password  to  use  on  the  proxy. 

The  function  returns  an  associative  array  of  the  keys  and  values  in  the  response. 

Nota:  Be  sure  to  read  the  Payflow  Pro  Developers  Guide  for  full  details  of  the  required  parameters. 


Ejemplo  1.  Payflow  Pro  example 


<?php 


pfpro_init ( )  ; 

$transaction  =  array (USER  =>  'mylogin', 
PWD  =>  ' mypassword' , 

TRXTYPE  =>  'S', 

TENDER  =>  ' C'  , 

AMT  =>  1.50, 

ACCT  =>  '4111111111111111', 

EXPDATE  =>  '0904' 

)  ; 


$response  =  pfpro_process ( $transaction) ; 
if  ( ! {response)  { 

die ( "Couldn' t  establish  link  to  Verisign . \n" ) ; 

} 

echo  "Verisign  response  code  was  {response [RESULT] ; 
echo  ",  which  means:  " . {response [RESPMSG] . " \n" ; 

echo  "\nThe  transaction  request:  " ; 
print_r ({transaction) ; 

echo  "\nThe  response: 
print_r ({response) ; 

pfpro_cleanup ( ) ; 

?> 
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pf  pro_process_raw  (php  4  >=  4.0.2) 


Process  a  raw  transaction  with  Payflow  Pro 


string  pfpro_process_raw  (string  parameters  [,  string  address  [,  int  port  [, 
int  timeout  [,  string  proxy  address  [,  int  proxy  port  [,  string  proxy  logon 
[,  string  proxy  password ] ]]]]]]) 


Returns:  A  string  containing  the  response. 

pfpro_process_raw()  processes  a  raw  transaction  string  with  Payflow  Pro.  You  should  really  use 
pfpro_process ')  instead,  as  the  encoding  rules  of  these  transactions  are  non-standard. 

The  first  parameter  in  this  case  is  a  string  containing  the  raw  transaction  request.  All  other  parameters  are 
the  same  as  with  pfpro_process').  The  return  value  is  a  string  containing  the  raw  response. 

Nota:  Be  sure  to  read  the  Payflow  Pro  Developers  Guide  for  full  details  of  the  required  parameters 
and  encoding  rules.  You  would  be  well  advised  to  use  pfpro_process;)  instead. 


Ejemplo  1.  Payflow  Pro  raw  example 

<?php 

pfpro_init ( )  ; 

$ response  =  pfpro_process ( "USER=mylogin&PWD [ 5 ] =m&ndy&TRXTYPE=S&TENDER=C&AMT=l . 50&ACCT=41111] 
if  ( ! $response)  { 

die ( "Couldn' t  establish  link  to  Verisign . \n" ) ; 

} 

echo  "Verisign  raw  response  was  ".{response; 
pfpro_cleanup ( ) ; 

?> 


pf  pro_version  (php  4  >=  4.o.2) 


Returns  the  version  of  the  Payflow  Pro  software 


string  pfpro_version  () 
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pfpro_version()  returns  the  version  string  of  the  Payflow  Pro  library.  At  the  time  of  writing,  this  was 
L21 1. 
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extensionjoaded  (PHP  3>=  3.0.10,  PHP  4  >=  4.0.0) 

averigua  si  una  extension  ha  sido  cargada 

bool  extension_loaded  (string  name) 

Devuelve  true  si  la  extension  identificada  por  name  (nombre)  esta  cargada.  Puede  ver  el  nombre  de 
varias  extensiones  utilizando  phpinfo'). 

Vease  tambien  phpinfo'). 

Nota:  Esta  funcion  fue  anadida  en  3.0.1 0. 


getenv  (PHP  3,  PHP  4  >=  4.0.0) 

Obtiene  el  valor  de  una  variable  de  entorno 

string  getenv  (string  varname) 

Devuelve  el  valor  de  la  variable  de  entorno  varname,  o  false  en  caso  de  error. 

$ip  =  getenv ( "REMOTE_ADDR" ) ;  //  get  the  ip  number  of  the  user 

Puede  ver  una  lista  de  todas  las  variables  de  entorno  utilizando  phpinfo)).  Puede  encontrar  el  significado 
de  la  mayorfa  echando  un  vistazo  en  CGI  specification  (especificacion  CGI) 
(http://hoohoo.ncsa.uiuc.edu/cgi/),  especialmente  en  page  on  environmental  variables  (pagina  de 
variables  de  entorno)  (http://hoohoo.ncsa.uiuc.edu/cgi/env.html). 


get_cfg_var  (PHP  3,  PHP  4  >=4.0.0) 

Obtiene  el  valor  de  una  opcion  de  configuration  de  PHP. 

string  get_cfg_var  (string  varname) 
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Devuelve  el  valor  actual  de  una  variable  de  configuracion  de  PHP  especificada  en  varname,  o  false  si 
ocurre  un  error. 

No  devolvera  informacion  de  la  configuracion  cuando  el  PHP  fue  compilado,  o  lefdo  desde  un  fichero  de 
configuracion  Apache  (utilizando  las  directivas  php3_configuration_option  directives). 

Para  comprobar  si  el  sistema  esta  utilizando  un  fichero  de  configuracion  intente  recuperar  el  valor  de 
cfg_file_path.  Si  esta  disponible,  se  esta  utilizando  un  fichero  de  configuracion. 


get_current_user  (PHP  3,  PHP  4  >=4.0.0) 

Obtiene  el  nombre  del  propietario  del  script  PHP  actual, 
string  get_current_user  (void) 

Devuelve  el  nombre  del  propietario  del  script  PHP  actual. 

Vease  tambien  getmyuid'),  getmypid'),  getmyinodeO,  y  get  last  mod '). 

g  et_mag  i  c_q  u  otes_g  pc  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 

Obtiene  el  valor  de  la  configuracion  activa  actual  de  las  comillas  magicas  gpc. 

long  get_magic_quotes_gpc  (void) 

Devuelve  el  valor  de  la  configuracion  activa  actual  de  magic_quotes_gpc  (0  desactivado,  1  activado) 
Vease  tambien  get_magic_quotes_runtime  {),  set_magi c_q uotes_ru nti  me ' ) . 

get_magic_quotes_runtime  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 

Obtiene  el  valor  de  la  configuracion  activa  actual  de  magic_quotes_runtime. 

long  getmagic_quotes_runtime  (void) 

Devuelve  el  valor  de  la  configuracion  activa  actual  de  magic_quotes_runtime  (0  desactivado,  1  activado) 
Vease  tambien  get_magic_quotes_gpc\),  set_magic_quotes_runtimeO- 
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opciones/informacion  PHP 


Recupera  la  fecha/hora  de  la  ultima  modificacion  de  la  pagina. 


int  getlastmod  (void) 


Devuelve  la  fecha/hora  de  la  ultima  modificacion  de  la  pagina  actual.  El  valor  devuelto  esta  en  formato 
de  fecha/hora  Unix,  adecuado  para  que  sirva  a  date /).  Devuelve  false  en  caso  de  error. 

Ejemplo  1.  ejemplo  getlastmod() 

//  outputs  e.g.  'Last  modified:  March  04  1998  20:43:59.' 
echo  "Last  modified:  ",date(  "F  d  Y  H:i:s.",  getlastmod ( )  ); 


Vease  tambien  date'),  getmyuid/),  get_currcnt_user  ),  getmyinode/),  y  getmypid''). 

getmyinode  (PHP  3,  PHP  4  >=  4.0.0) 

Recupera  el  inodo  del  script  actual. 

int  getmyinode  (void) 

Devuelve  el  inodo  del  script  actual,  o  false  en  caso  de  error. 

Vease  tambien  getmyuid/),  get_current_user/),  getmypid/),  y  getlastmod/). 


getmypid  (PHP  3,  PHP  4  >=  4.0.0) 

Obtiene  el  ID  de  proceso  de  PHP. 

int  getmypid  (void) 


Devuelve  el  ID  del  proceso  PHP  actual,  o  false  en  caso  de  error. 

Advierta  que  cuando  se  ejecuta  como  un  modulo  de  servidor,  diferentes  llamadas  del  script  no  garantizan 
que  tengan  distintos  pids. 

Vease  tambien  getmyuid/),  get_current_user/),  getmyinode/),  y  getlastmod/). 
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getmyuid  (PHP  3,  PHP  4  >=  4.0.0) 

Obtiene  el  UID  del  propietario  del  script  PHP. 

int  getmyuid  (void) 

Devuelve  el  ID  de  usuario  del  script  actual,  o  false  en  caso  de  error. 

Vease  tambien  getmypidO,  get_current_user(),  getmyinodeO,  y  getlastmod)). 


getrusage  (PHP  3>=  3.0.7,  PHP  4  >=  4.0.0) 

Obtiene  el  consumo  actual  de  recursos. 


array  getrusage  ([int  who]) 


Es  un  interface  a  getrusage(2).  Devuelve  un  array  asociativo  que  contiene  los  datos  devueltos  de  la 
llamada  del  sistema.  Si  who  (quien)  es  1,  getrusage  deberfa  llamarse  con  RUSAGE_CHILDREN.  Todas 
las  entradas  son  accesibles  utilizando  sus  nombres  de  campo  documentados. 

Ejemplo  1.  Ejemplo  Getrusage 

$dat  =  getrusage (); 


echo 

$dat  | 

[ " ru_nswap" ] ; 

# 

number  of 

swaps 

echo 

$dat  | 

; " ru_ma j  f it " ] ; 

# 

number  of 

page 

faults 

echo 

$dat  | 

[ " ru_ut ime . tv_sec" ] ; 

# 

user  time 

used 

( seconds ) 

echo 

$dat  | 

[ " ru_ut ime . tv_usec" ] ; 

# 

user  time 

used 

(microseconds 

Vea  la  pagina  man  de  system  para  mas  detalles. 


phpinfo  (PHP  3,  PHP  4  >=4.0.0) 


Recupera  gran  cantidad  de  informacion  de  PHP. 


int  phpinfo  (void) 


Obtiene  gran  cantidad  de  informacion  sobre  el  estado  actual  de  PHP.  Esto  incluye  informacion  sobre  las 
opciones  de  compilation  y  extensiones  de  PHP,  la  version  PHP,  informacion  y  entorno  del  servidor  (si 
esta  compilado  como  un  modulo),  el  entorno  PHP,  informacion  sobre  la  version  del  SO,  rutas,  opciones 
de  configuration  maestras  y  locales,  cabeceras  HTTP,  y  la  Licencia  Publica  GNU. 
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Vease  tambien  phpversion '). 


phpversion  (PHP  3,  PHP  4  >=4.0.0) 


Obtiene  la  version  actual  de  PHP. 


string  phpversion  (void) 


Devuelve  una  cadena  de  caracteres  que  contiene  la  version  del  parser  PHP  que  esta  ejecutandose 
actualmente. 

Ejemplo  1.  ejemplo  phpversion() 

//  prints  e.g.  'Current  PHP  version:  3.0rel-dev' 
echo  "Current  PHP  version:  phpversion (); 


Vease  tambien  phpinfo)). 


php Jogo_guid  php 4 >=  4 o  0) 


Obtiene  el  guid  logo 


string  php_logo_guid  (void) 


Nota:  Esta  funcionalidad  fue  anadida  en  PHP4  Beta  4. 


putenv  (PHP  3,  PHP  4  >=  4.0.0) 


Establece  el  valor  de  una  variable  de  entorno. 


void  putenv  (string  setting) 
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Anade  setting  (valor)  al  entorno. 


Ejemplo  1.  Establecer  una  Variable  de  Entorno 

putenv ( "UNIQID=$uniqid" ) ; 


set_magic_quotes_runtime  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 

Establece  el  valor  de  la  configuracion  activa  actual  de  magic_quotes_runtime. 

long  set_magic_quotes_runtime  (int  new_setting) 

Establece  el  valor  de  la  configuracion  activa  actual  de  magic_quotes_runtime  (0  desactivado,  1  activado) 
Vease  tambien  get_magic_quotes_gpc\),  get_magic_quotes_runtime(). 


set_time_limit  (PHP  3,  PHP  4  >=  4.0.0) 

limita  el  tiempo  maximo  de  ejecucion 

void  set_time_limit  (int  seconds) 


Establece  el  numero  de  segundos  que  se  le  permite  a  un  script  ejecutarse.  Si  este  es  alcanzado,  el  script 
devuelve  un  error  de  tipo  fatal.  El  lfmite  por  defecto  es  30  segundos  o,  si  existe,  el  valor 
max_execution_time  definido  en  el  fichero  de  configuracion  Si  seconds  (segundos)  se  establece  a  cero, 
no  se  impone  ningun  lfmite. 

Cuando  se  llama,  set_time_limit()  reinicia  el  contador  del  timeout  a  cero.  En  otras  palabras,  si  el  timeout 
es  el  de  por  defecto  de  30  segundos,  y  despues  de  25  segundos  de  ejecucion  del  script  se  realiza  una 
llamada  set_time_limit(20),  el  script  se  ejecutara  durante  un  total  de  45  segundos  antes  de  alcanzar  su 
lfmite. 

Advierta  que  set_tiine_limit()  no  tiene  efecto  cuando  PHP  se  ejecuta  en  modo  seguro  (safe  mode).  No 
hay  otra  opcion  que  que  desactivar  el  modo  seguro  o  cambiar  el  lfmite  de  tiempo  en  el  fichero  de 
configuracion 
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zendJogo_guid  (php4>=4.o.o) 


Obtiene  el  guid  zend 


string  zend_logo_guid  (void) 


Nota:  Esta  funcionalidad  fue  anadida  en  PHP4  Beta  4. 
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LXVI.  Funciones  POSIX 


Este  modulo  contiene  una  interfaz  a  aquellas  funciones  definidas  en  el  documento  estandar  IEEE  1003.1 
(POSIX.  1)  que  no  son  accesibles  de  otra  manera.  POSIX.  1  por  ejemplo  definio  las  funciones 
open(),read(),  write()  y  closeQ,  las  cuales  han  sido  parte  de  PHP  durante  mucho  tiempo.Algunas 
funciones  especfficas  del  sistema  no  habian  estado  disponibles  antes,  aunque  con  este  modulo  se  intenta 
remediar  esto  ofreciendo  un  acceso  facil  a  esas  funciones. 
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posix  kill  (PHP  3>=  3.0.13,  PHP  4  >=  4.0.0) 
Manda  una  senal  a  un  proceso 

bool  posix_kill  (int  pid,  int  sig) 


Manda  la  senal  sig  al  proceso  con  el  identificador  de  proceso  pid.  Devuelve  false,  si  no  puede  enviar 
la  seiial. Si  si  la  envia  devuelve  true  . 

Vea  tambien  la  pagina  de  manual  kill(2)  de  su  sistema  POSIX,  la  cual  contiene  information  adicional 
sobre  los  identific adores  de  proceso  negativos,  el  pid  especial  0,  el  pid  especial  -1,  y  la  senal  numero  0. 


posix_getpid  (PHP  3>=  3.0.10,  PHP  4  >=  4.0.0) 

Devuelve  el  identificador  del  proceso  actual 

int  posix_getpid  (void  ) 


Devuelve  el  identificador  de  proceso  del  proceso  actual. 


posix_getppid  (PHP  3>=  3.0.10,  PHP  4  >=  4.0.0) 

Devuelve  el  identificador  del  proceso  padre 

int  posix_getppid  (void  ) 


Devuelve  el  identificador  de  proceso  del  proceso  padre  del  proceso  actual. 


posix_getuid  (PHP  3>=  3.0.10,  PHP  4  >=  4.0.0) 

Devuelve  el  ID  de  usuario  real  del  proceso  actual 

int  posix_getuid  (void  ) 
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Devuelve  el  valor  numerico  ID  de  usuario  real  del  proceso  actual.  Vea  tambien  posix_getpwuid ')  para 
information  sobre  como  convertir  este  ID  en  un  nombre  de  usuario  manejable. 


posix_geteuid  (PHP  3>=  3.0.10,  PHP  4  >=  4.0.0) 

Devuelve  el  ID  de  usuario  efectivo  del  proceso  actual 

int  posix_geteuid  (void  ) 


Devuelve  el  valor  numerico  ID  de  usuario  efectivo  del  proceso  actual.  Vea  tambien  posix_getpwuid') 
para  informacion  sobre  como  convertir  este  numero  en  un  nombre  de  usuario  manejable. 


posix_getgid  (PHP  3>=  3.0.10,  PHP  4  >=  4.0.0) 

Devuelve  el  ID  de  grupo  real  del  proceso  actual 

int  posix_getgid  (void  ) 


Devuelve  el  valor  numerico  ID  de  grupo  real  del  proceso  actual.  Vea  tambien  posix_getgrgid')  para 
informacion  sobre  como  convertir  esto  en  un  nombre  de  grupo  manejable. 


posix_getegid  (PHP  3>=  3.0.10,  PHP  4  >=  4.0.0) 

Devuelve  el  ID  de  grupo  efectivo  del  proceso  actual 

int  posix_getegid  (void  ) 


Devuelve  el  valor  numerico  ID  de  grupo  efectivo  del  proceso  actual.  Vea  tambien  posix_getgrgid  )  para 
informacion  sobre  como  convertir  este  numero  en  un  nombre  de  grupo  manejable. 


posix_setuid  (PHP  3>=  3.0.13,  PHP  4  >=  4.0.0) 

Asigna  el  UID  efectivo  del  proceso  actual 
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bool  posix_setuid  (int  uid) 


Asigna  el  ID  de  usuario  real  al  proceso  actual.  Esta  es  una  funcion  privilegiada  y  necesitas  los  privilegios 
apropiados  (normalmente  root)  en  tu  sistema  para  realizar  esta  funcion. 

Devuelve  true  si  tiene  exito,  false  en  caso  contrario.  Yea  tambien  posix_setgid  ). 


posix_setgid  (PHP  3>=  3.0.13,  PHP  4  >=  4.0.0) 

Asigna  el  GID  efectivo  del  proceso  actual 


bool  posix_setgid  (int  gid) 


Asigna  el  ID  de  grupo  real  del  proceso  actual.  Esta  es  una  funcion  privilegiada  y  necesitas  los  privilegion 
apropiados  (normalmente  root)  en  tu  sistema  para  realizar  esta  funcion.  El  orden  apropiado  de  llamada  es 
posix_setgid()  primero,  posix_setuid')  despues. 

Devuelve  true  si  tiene  exito,  false  en  caso  contrario. 


posix_getgroups  (PHP  3>=  3.0.10,  PHP  4  >=  4.0.0) 

Devuelve  el  conjunto  de  grupos  del  proceso  actual 

array  posix_getgroups  (void  ) 

Devuelve  un  vector  de  enteros  que  contiene  los  ids  numericos  de  grupo  de  el  conjunto  de  grupos  del 
proceso  actual.  Vea  tambien  posix_getgrgid0  para  informacion  sobre  como  convertir  esto  en  nombres  de 
grupo  manejables. 


posix_getlogin  (PHP  3>=  3.0.13,  PHP  4  >=  4.0.0) 

Devuelve  el  nombre  de  usuario 

string  posix_getlogin  (void  ) 
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Devuelve  el  nombre  de  usuario  (login)  que  es  dueno  del  proceso  actual.  Vea  posix_getpwnam()  para 
informacion  sobre  como  conseguir  mas  datos  de  este  usuario. 


posix_getpgrp  (PHP  3>=  3.0.10,  PHP  4  >=  4.0.0) 

Devuelve  el  identificador  de  grupo  del  proceso  actual 

int  posix_getpgrp  (void  ) 


Devuelve  el  identificador  de  grupo  de  proceso  del  proceso  actual.  Vea  POSIX.  1  y  la  pagina  de  manual 
getpgrp(2)  de  su  sistema  POSIX  para  mas  informacion  de  grupos  de  procesos. 


posix_setsid  (PHP  3>=  3.0.13,  PHP  4  >=  4.0.0) 

Convierte  el  proceso  actual  en  lider  de  sesion 

int  posix_setsid  (void  ) 


Convierte  el  proceso  actual  en  lider  de  sesion.  Vea  POSIX.  1  y  la  pagina  de  manual  setsid(2)  en  su  sistema 
POSIX  para  mas  informacion  en  grupos  de  proceso  y  control  de  trabajos.  Devuelve  el  id  de  sesion. 


posix_setpgid  (PHP  3>=  3.0.13,  PHP  4  >=  4.0.0) 

Asigna  el  id  de  grupo  de  procesos  para  el  control  de  trabajos 

int  posix_setpgid  (int  pid,  int  pgid) 


Inserta  el  proceso  pi  d  en  el  grupo  de  procesos  pgi  d.  Vea  POSIX.  1  y  la  pagina  de  manual  setsid(2)  de 
su  sistema  POSIX  para  mas  informacion  sobre  grupos  de  procesos  y  control  de  trabajo.  Devuelve  true 
si  tiene  exito  y  false  en  caso  contrario. 


posixgetpgid  (PHP  3>=  3.0.10,  PHP  4  >=  4.0.0) 

Recoge  el  id  del  grupo  de  procesos  para  el  control  de  trabajo 
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int  posix_getpgid  (int  pid) 

Devuelve  el  identificador  de  grupo  de  procesos  del  proceso  pid. 

Esta  no  es  una  funcion  POSIX,  pero  es  normal  en  sistemas  BSD  y  System  V.  Si  su  sistema  no  soporta 
esta  funcion  a  nivel  de  sistema,  esta  funcion  PHP  devolvera  siempre  false. 

posix_getsid  (PHP  3>=  3.0.10,  PHP  4  >=  4.0.0) 

Consigue  el  sid  actual  del  proceso 

int  posix_getsid  (int  pid) 

Devuelve  el  sid  del  proceso  pid.  Si  pid  es  0,  se  devolvera  el  sid  del  proceso  actual. 

Esta  no  es  una  funcion  POSIX,  pero  es  normal  en  sistemas  System  V.  Si  su  sistema  no  soporta  esta 
funcion  a  nivel  de  sistema,  esta  funcion  PHP  devolvera  siempre  false. 


posixuname  (PHP  3>=  3.0.10,  PHP  4  >=  4.0.0) 

Consigue  el  nombre  del  sistema 

array  posix_uname  (void  ) 


Devuelve  un  hash  de  cadenas  con  information  sobre  el  sistema.  Los  Indices  del  hash  son 

•  sysname  -  nombre  del  sistema  operativo  (e.g.  Linux) 

•  nodename  -  nombre  del  sistema  (e.g.  valiant) 

•  release  -  release  del  sistema  operativo  (e.g.  2.2.10) 

•  version  -  version  del  sistema  operativo  (e.g.  #4  Tue  Jul  20  17:01:36  MEST  1999) 

•  machine  -  arquitectura  del  sistema  (e.g.  i586) 

Posix  requiere  que  usted  no  debe  hacer  ninguna  suposicion  sobre  el  formato  de  los  valores,  por  ejemplo 
usted  no  puede  confiar  en  los  tres  dlgitos  de  la  version  o  cualquier  cosa  devuelta  por  esta  funcion. 
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posix_times  (PHP  3>=  3.0.13,  PHP  4  >=  4.0.0) 

Recoge  el  tiempo  de  los  procesos 

array  posix_times  (void  ) 


Devuelve  un  hash  de  cadenas  con  information  sobre  el  uso  de  CPU  del  proceso  actual.  Los  indices  del 
hash  son 

•  ticks  -  el  numero  de  ticks  de  reloj  que  han  pasado  desde  el  reinicio. 

•  utime  -  tiempo  de  usuario  usado  por  el  proceso  actual. 

•  stime  -  tiempo  de  sistema  usado  por  el  proceso  actual. 

•  cutime  -  tiempo  de  usuario  usado  por  el  proceso  actual  e  hijos. 

•  cstime  -  tiempo  de  sistema  usado  por  el  proceso  actual  e  hijos. 


posix_ctermid  (PHP  3>=  3.0.13,  PHP  4  >=  4.0.0) 

Recoge  el  nombre  de  ruta  de  la  terminal  de  control 

string  posix_ctermid  (void  ) 


Necesita  ser  escrito. 


posix_ttyname  (PHP  3>=  3.0.13,  PHP  4  >=  4.0.0) 

Determina  el  nombre  del  dispositivo  terminal 

string  posix_ttyname  (int  fd) 


Necesita  ser  escrito. 
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posix_isatty  (PHP  3>=  3.0.13,  PHP  4  >=  4.0.0) 

Determina  si  un  descriptor  de  fichero  esta  en  una  terminal  interactiva 

bool  posix_isatty  (int  fd) 


Necesita  ser  escrito. 


posix_getcwd  (PHP  3>=  3.0.13,  PHP  4  >=  4.0.0) 

Nombre  de  ruta  del  directorio  actual 


string  posix_getcwd  (void  ) 


Necesita  ser  escrito  cuanto  antes. 


posixmkfifo  (PHP  3>=  3.0.13,  PHP  4  >=  4.0.0) 

Crea  un  fichero  especial  fifo  (los  llamados  pipe  o  tuberias) 

bool  posix_getcwd  (string  pathname,  int  mode) 


Necesita  ser  escrito  lo  mas  pronto  posible. 


posix_getgrnam  (PHP  3>=  3.0.13,  PHP  4  >=  4.0.0) 

Devuelve  information  sobre  un  grupo  a  traves  del  nombre 

array  posix_getgrnam  (string  name) 


Necesita  ser  escrito. 
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posix_getgrgid  (PHP  3>=  3.0.13,  PHP  4  >=  4.0.0) 


Devuelve  information  sobre  un  grupo  a  trave  del  id  de  grupo 


array  posix_getgrgid  (int  gid) 


Necesita  ser  escrito. 


posix_getpwnam  (PHP  3>=  3.0.13,  PHP  4  >=  4.0.0) 


Devuelve  informacion  sobre  un  usuario  a  traves  del  nombre  de  usuario 


array  posix_getpwnam  (string  username) 


Devuelve  un  vector  asociativo  conteniendo  information  sobre  un  usuario  referenciado  por  un  nombre 
alfanumerico,  pasado  a  la  funcion  en  el  parametro  username. 

Los  elementos  del  vector  devuelto  son: 


Tabla  1.  El  vector  de  informacion  de  usuario 


Elemento 

Descripcion 

name 

El  elemento  name  contiene  el  nombre  de  usuario 

del  usuario.  Este  es  un  nombre,  normalmente  menor 
de  16  caracteres,  que  no  es  su  nombre  completo, 
pero  identifica  al  usario.  Este  debe  ser  el  mismo  que 
el  parametro  username  usado  en  la  llamada  a  la 
funcion  y  por  lo  tanto  es  redundante. 

passwd 

El  elemento  passwd  contiene  la  contrasena  del 
usuario  en  un  formato  encriptado.  Normalmente, 
por  ejemplo  en  un  sistema  que  este  utilizando 
contrasenas  "shadow",  devolvera  un  asterisco. 

uid 

El  ID  de  usuario  del  usuario  en  formato  numerico. 

gid 

El  ID  de  grupo  del  usuario.  Utiliza  la  funcion 
posix_getgrgid ')  para  resolver  el  nombre  del  grupo 
y  una  lista  de  sus  miembros. 
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Elemento 

Descripcion 

gecos 

GECOS  es  un  termino  obsoleto  que  se  refiere  al 
campo  apuntado  de  information  en  un  sistema  de 
procesamiento  batch  Honeywell.  El  campo  y  sus 
contenidos  han  sido  formalizado  por  POSIX  y 
contiene  una  lista  separada  por  comas  con  el 
nombre  completo  del  usuario,  telefono  del  trabajo, 
numero  de  oficina  y  telefono  de  casa.  En  muchos 
sistemas  solo  esta  disponible  el  nombre  completo 
del  usuario. 

dir 

Este  elemento  contiene  la  ruta  absoluta  al  directorio 
del  usuario  (directorio  home). 

shell 

El  elemento  shell  contiene  la  ruta  absoluta  al 
ejecutable  del  shell  por  defecto  del  usuario. 

posix_getpwuid  (PHP  3>=  3.0.13,  PHP  4  >=  4.0.0) 


Devuelve  information  sobre  un  usuario  a  traves  de  su  id 


array  posix_getpwuid  (int  uid) 


Devuelve  un  vector  asociativo  que  contiene  information  sobre  un  usuario  referenciado  con  un  ID  de 
usuario,  pasado  por  el  parametro  uid. 

Los  elementos  del  array  son: 


Tabla  1.  El  vector  de  information  del  usuario 


Elemento 

Descripcion 

name 

El  elemento  name  contiene  el  nombre  de  usuario 

del  usuario.  Este  es  un  nombre,  normalmente  menor 
de  16  caracteres,  que  no  es  su  verdadero  nombre. 

passwd 

El  elemento  passwd  contiene  la  contrasena  del 
usuario  en  un  formato  encriptado.  Normalmente, 
por  ejemplo  en  un  sistema  con  contrasenas 
"shadow",  devolvera  un  asterisco. 

uid 

ID  del  usuario,  debe  ser  el  mismo  que  el  parametro 
uid  usado  en  la  llamada  a  la  funcion,  y  por  lo  tanto 
redundante. 
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Elemento 

Descripcion 

gid 

El  ID  del  grupo  del  usuario.  Utiliza  la  funcion 
posix_getgrgid ')  para  resolver  el  nombre  del  grupo 
y  una  lista  de  sus  miembros. 

gecos 

GECOS  es  un  termino  obsoleto  que  se  refiere  al 
campo  apuntado  de  de  informacion  en  un  sistema  de 
procesamiento  batch  Honeywell.  El  campo  y  sus 
contenidos  han  sido  formalizados  por  POSIX  y 
contiene  una  lista  separada  por  comas  con  el 
nombre  completo  del  usuario,  telefono  del  trabajo, 
numero  de  oficina  y  telefono  de  casa.  En  muchos 
sistemas  solo  esta  disponible  el  nombre  completo 
del  usuario. 

dir 

Este  elemento  contiene  la  ruta  absoluta  al  directorio 
del  usuario  (directorio  home). 

shell 

El  elemento  shell  contiene  la  ruta  absoluta  al 
ejecutable  del  shell  por  defecto  del  usuario. 

posix_getrlimit  (PHP  3>=  3.0.10,  PHP  4  >=  4.0.0) 

Devuelve  information  sobre  los  limites  de  recursos  del  sistema 


array  posix_getrlimit  (void  ) 


Necesita  ser  escrita  tan  pronto  como  sea  posible. 
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LXVII.  Funciones  de  PostgreSQL 

Postgres,  desarrollado  originalmente  en  el  UC  Berkeley  Computer  Science  Department,  ha  sido  pionero 
en  muchos  de  los  conceptos  relacionales/orientados  a  objeto  que  ahora  estan  empezando  a  estar 
disponibles  en  algunas  bases  de  datos  comperciales.  Tiene  soporte  de  lenguaje  SQL92/SQL3,  integridad 
transaccional,  y  extensibilidad  de  tipos.  PostgreSQL  es  un  descendiente  de  dominio  publico,  mas 
concretamente  open  source,  del  codigo  original  de  Berkeley. 

PostgreSQL  se  encuentra  disponible  sin  coste  alguno.  La  version  actual  la  tienes  a  tu  disposition  en 
www.PostgreSQL.org (http://www.postgresql.org/). 

Desde  la  version  6.3  (02/03/1998)  PostgreSQL  usa  sockets  tipo  Unix.  Abajo  se  da  una  tabla  con  las 
diferentes  posibilidades.  El  socket  se  encuentra  en  el  ficheero  /tmp/  .  s  .  PGSQL .  5432.  Esta  option  se 
controla  mediante  el  flag  ’-i’  del  postmaster  y  cuando  se  incluye  significa  "escuchar  sockets  TCP/IP 
ademas  de  los  de  dominio  Unix"  ya  que  si  no  se  le  dice  nada  solo  escucha  sockets  tipo  Unix. 


Tabla  1.  Postmaster  y  PHP 


Postmaster 

PHP 

Estado 

postmaster  & 

pg_connect("", 

"dbname"); 

OK 

postmaster  -i  & 

pg_connect("", 

"dbname"); 

OK 

postmaster  & 

pg_connect("localhost", 

"dbname"); 

Unable  to  connect  to  PostgreSQL 
server:  connectDBQ  failed:  Is  the 
postmaster  running  and  accepting 
TCP/IP  (with  -i)  connection  at 
’localhost’  on  port  ’5432’?  in 
/path/to/file. php3  on  line  20. 
(Imposible  conectar  al  servidor 
PostgreSQL,  la  llamada 
connectDB()  ha  fallado:  /  Esta 
funcionando  el  postmaster 
aceptando  conextiones  TCP/IP 
(con  -i)  en  ’localhost’  en  el  puerto 
’5432’?  en  /path/to/file. php3  en 
linea  20. 

postmaster  -i  & 

pg_connect("localhost", 

"dbname"); 

OK 

Uno  puede  establecer  una  conexion  con  el  siguiente  comando: 

Para  usar  el  interface  de  objetos  grandes  (large  object  o  lo),  es  necesario  encapsularlo  en  un  bloque  de 
transaccion.  Un  bloque  de  transaccion  empieza  con  un  begin  y  si  la  transaccion  fue  valida  termina  con 
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commit  y  end.  Si  la  transaccion  falla  debe  ser  cerrada  con  abort  y  rollback. 
Ejemplo  1.  Usando  Objetos  Grandes  (lo) 

<?php 

$database  =  pg_Connect  "jacarta"); 

pg_exec  ($database,  "begin"); 

$oid  =  pg_locreate  ($database) ; 
echo  ("$oid\n"); 

$handle  =  pg_loopen  ($database,  $oid,  "w"); 
echo  ( " $handle\n" ) ; 
pg_lowrite  ($handle,  "gaga"); 
pg_loclose  ($handle) ; 
pg_exec  ($database,  "commit") 
pg_exec  ($database,  "end") 

?> 
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pg_Close  (PHP  3,  PHP  4  >=  4.0.0) 

Cierra  una  conexion  PostgreSQL 

bool  pg_close  (int  connection) 

Devuelve  false  si  connection  no  es  un  indice  de  conexion  valido  y  true  en  cualquier  otro  caso.  Cierra 
la  conexion  a  la  base  de  datos  PostgreSQL  asociada  con  el  indice  de  conexion  pasado  como  parametro. 


pg_cmdTuples  <php  3,  php 4  >=  4 o o> 

Devuelve  el  numero  de  tuplas  afectadas 

int  pg_cmdtuples  (int  result_id) 


pg_cmdTuples()  devuelve  el  numero  de  tuplas  (instancias  o  filas)  afectadas  por  consultas  INSERT, 
UPDATE  y  DELETE.  Si  no  hay  ninguna  tupla  afectada  la  funcion  devolvera  0. 

Ejemplo  1.  pg_cmdtuples 


<?php 

$result  =  pg_exec ( $conn,  "INSERT  INTO  verlag  VALUES  ( ' Autor ' ) " ) ; 

$cmdtuples  =  pg_cmdtuples ($result) ; 

echo  $cmdtuples  .  "  <-  cmdtuples  affected."; 

?> 


pg_Connect  (PHP  3,  PHP  4  >=  4.0.0) 


Abre  una  conexion 


int  pg_connect  (string  host,  string  port,  string  options,  string  tty,  string 
dbn ame) 


Devuelve  un  mdice  de  conexion  en  caso  de  exito,  o  falso  si  la  conexion  no  se  puede  realizar.  Esta  funcion 
abre  una  conexion  a  una  base  de  datos  PostgreSQL.  Cada  uno  de  los  argumentos  debe  ser  una  cadena 
entrecomillada,  incluyendo  el  numero  de  puerto.  Los  parametros  options  y  tty  son  opcionales  y  pueden 
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ser  omitidos.  Esta  funcion  devuelve  un  indice  de  conexion  que  se  necesitara  para  otxas  funciones 
PostgreSQL.  Puedes  tener  multiples  conexiones  abiertas  al  mismo  tiempo. 

Una  conexion  tambien  se  puede  establecer  con  el  siguiente  comando:  $conn  = 

pg_connect("dbname=marliese  port=5432");  Otros  parametros  aparte  de  dbname  y  port  son  host, 
tty,  options,  user  y  password. 

Ver  tambien  pg_pConnect(). 


pg_DBname  (PHP  3,  PHP  4  >=  4.0.0) 


Nombre  de  la  base  de  datos 


string  pg_dbname  (int  connection) 


Devuelve  el  nombre  de  la  base  de  datos  a  la  cual  es  el  mdice  de  conexion  con  PostgreSQL  esta 
conectado,  o  false  si  connection  no  es  un  mdice  de  conexion  valido. 


pg_ErrorMessage  (php  3,  php  4  >=  4.o.0) 


mensaje  de  error 


string  pg_errormessage  (int  connection) 


Devuelve  una  cadena  que  contiene  el  mensaje  de  error,  o  false  en  caso  de  fallo.  Probablemente  no  se 
podran  obtener  los  detalles  del  error  a  traves  de  la  funcion  pg_errormessage()  si  ocurre  un  error  en  la 
ultima  action  de  base  de  datos  para  la  cual  existe  una  conexion  valida,  esta  funcion  retornara  una  cadena 
conteniendo  el  mensaje  de  error  generado  por  el  servidor  "backend". 


pg_Exec  (PHP  3,  PHP  4  >=  4.0.0) 

Ejecuta  una  consulta  (query) 

int  pg_exec  (int  connection,  string  query) 


Devuelve  un  mdice  de  resultado  si  se  pudo  ejecutar  la  consulta,  o  false  en  caso  de  fallo  o  si  connection 
no  es  un  mdice  de  conexion  valido.  Se  pueden  obtener  detalles  acerca  del  error  mediante  la  funcion 
pg_ErrorMessage()  siempre  que  conection  sea  valido.  Envia  una  sentencia  SQL  a  la  base  de  datos 
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PostgreSQL  especificada  por  el  fndice  de  conexion.  connection  debe  ser  un  fndice  valido  devuelto  por 
pg_Connect().  El  valor  de  devuelto  por  esta  funcion  es  un  fndice  para  ser  usado  al  acceder  a  los 
resultados  de  la  consulta  desde  otras  funciones  PostgreSQL. 

Nota:  PHP/FI  devuelvfa  1  si  no  es  una  consulta  que  tenga  que  devolver  datos  (inserts  o  updates, 
por  ejemplo)  y  un  valor  mayor  que  1  incluso  en  el  caso  de  selects  que  no  devolvieron  nada.  En  PHP 
no  se  puede  contar  con  ninguna  de  esas  suposiciones. 


pg_Fetch_Array  (php  3>=  3.0.1  php  4  >=  4.0.0) 

obtiene  una  fila  en  la  forma  de  un  array 

array  pg_fetch_array  (int  result,  int  row  [,  int  result_type] ) 


Devuelve:  Un  array  que  se  corresponde  con  la  fila  obtenida,  o  false  si  no  hay  mas  filas. 

pg_fetch_array()  es  una  version  extendida  de  pg_fetch_row ').  Ademas  de  almacenar  los  datos  en  los 
indices  numericos  del  array  resultante,  tambien  almacena  los  datos  usando  indices  asociativos, 
empleando  para  ello  el  nombre  del  campo  como  la  Have  o  fndice. 

El  tercer  parametro  opcional  result_type  en  pg_fetch_array()  es  una  constante  y  puede  tomar 
cualquiera  de  los  siguientes  valores:  PGSQL_ASSOC,  PGSQL_NUM,  y  PGSQL_BOTH. 

Nota:  Result_type  se  anadio  en  PHP  4.0. 


Una  cosa  importante  a  tener  en  cuenta  es  que  usar  pg_fetch_array()  NO  es  significativamente  mas  lento 
que  usar  pg_fetch_row '),  y  sin  embargo  el  valor  anadido  que  aporta  sf  lo  es. 

Para  mas  detalles,  ver  pg_fetch_row ') 

Ejemplo  1.  PostgreSQL  fetch  array 


<?php 

$conn  =  pg_pconnect ", "publisher ") ; 
if  ( ! $conn)  { 

echo  "An  error  occured.Xn"; 
exit; 

} 

$result  =  pg_Exec  ($conn,  "SELECT  *  FROM  authors"); 
if  ( ! $result)  { 

echo  "An  error  occured.\n"; 


877 


PostgreSQL 


exit; 

} 

$arr  =  pg_f etch_array  ($result,  0); 
echo  $arr[0]  .  "  <-  arrayXn"; 

$arr  =  pg_f etch_array  ($result,  1); 
echo  $arr [ "author" ]  .  "  <-  arrayXn"; 

?> 


pg_Fetch_Object  (PHP  3>=  3.0.1 ,  PHP  4  >=  4.0.0) 


obtener  una  fila  en  forma  de  objeto 


object  pg_fetch_ob ject  (int  result,  int  row  [,  int  result_type] ) 


Devuelve:  Un  objeto  cuyas  propiedades  se  corresponden  con  los  campos  de  la  fila  obtenida,  o  false  si 
no  hay  mas  filas. 

pg_fetch_object()  es  parecida  a  pg_fetch_arrayO,  con  una  diferencia  -  se  devuelve  un  objeto,  en  vez  de 
un  array.  Indirectamente,  eso  significa  que  solo  puedes  acceder  a  los  datos  por  medio  de  su  nombre  de 
campo,  y  no  a  traves  de  sus  posiciones  (los  numeros  son  nombres  de  propiedad  invalidos). 

El  tercer  parametro  opcional  result_type  en  pg_fetch_object()  es  una  constante  y  puede  tomar 
cualquiera  de  los  siguientes  valores:  PGSQL_ASSOC,  PGSQL_NUM,  y  PGSQL_BOTH. 

Nota:  Result_type  se  anadio  en  PHP  4.0. 


Referente  a  la  velocidad,  la  funcion  es  identica  a  pg_fetch_array0,  y  practicamente  tan  rapida  como 
pg_fetch_row0  (la  diferencia  es  insignificante). 

Ver  tambien:  pg_fetch_array ')  y  pg_fetch_row '). 

Ejemplo  1.  Postgres  fetch  object 


<?php 

$database  =  "verlag"; 

$db_conn  =  pg_connect  ( "localhost " ,  "5432",  $database) ; 

if  (!$db_conn) :  ?> 

<Hl>Failed  connecting  to  postgres  database  <?  echo  $database  ?></Hl>  <? 
exit ; 
endif ; 

$qu  =  pg_exec  ($db_conn,  "SELECT  *  FROM  verlag  ORDER  BY  autor") ; 
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$row  =  0;  //  postgres  needs  a  row  counter  other  dbs  might  not 

while  ($data  =  pg_f etch_ob ject  ($qu,  $row) ) : 
echo  $data->autor . "  ("; 

echo  $data->jahr  .") :  "; 

echo  $data->titel . " <BR> " ; 

$row++; 
endwhile;  ?> 

<PREX?php 

$f ields [ ]  =  Array  ("autor",  "Author"); 

$f ields [ ]  =  Array  ("jahr",  "  Year"); 

$fields[]  =  Array  ("titel",  "  Title"); 

$row=  0;  //  postgres  needs  a  row  counter  other  dbs  might  not 
while  ($data  =  pg_f etch_ob ject  ($qu,  $row) ) : 

echo  " - \n"; 

reset  ($fields) ; 

while  (list  (,$item)  =  each  ($fields)): 

echo  $item[l].":  " . $data->$item [ 0 ] . " \n" ; 

endwhile; 

$row++; 

endwhile; 

echo  " - \n";  ?> 

</PRE>  <?php 

pg_f reeResult  ($qu) ; 

pg_close  ($db_conn) ; 

?> 


pg_Fetch_Row  (PHP  3>=  3.0.1 ,  PHP  4  >=  4.0.0) 

obtiene  la  fila  como  un  array  enumerado 

array  pg_fetch_row  (int  result,  int  row ) 


Devuelve:  Un  array  que  se  corresponde  con  la  fila  obtenida,  o  false  en  el  caso  de  que  no  haya  mas  bias. 

pg_fetch_row()  obtiene  una  fila  de  datos  a  partir  del  resultado  asociado  con  el  identificador  de  resultado 
especificado.  La  fila  se  devuelve  en  forma  de  array.  Cada  columna  del  resultado  se  almacena  en  una 
posicion  del  array,  empezando  a  partir  de  la  posicion  0. 

Las  siguientes  llamadas  a  pg_fetch_row()  devolveran  la  fila  siguiente  en  el  conjunto  resultado,  o  falso  en 
el  caso  de  que  no  haya  mas  bias  que  devolver. 

Ver  tambien:  pg_fetch_array  [),  pg_fetch_object(),  pg_result'). 


879 


PostgreSQL 


Ejemplo  1.  Postgres  fetch  row 

<?php 

$conn  =  pg_pconnect "publisher ")  ; 
if  ( ! $conn)  { 

echo  "An  error  occured.\n"; 
exit ; 

} 

$result  =  pg_Exec  ($conn,  "SELECT  *  FROM  authors"); 
if  (  ! $result)  { 

echo  "An  error  occured.Xn"; 
exit ; 

} 


$row 

=  pg_ 

_f etch_ 

row 

($result, 

0)  ; 

echo 

$row  | 

:oi  .  " 

<- 

row\n" ; 

$row 

=  pg_ 

_f etch_ 

row 

($result, 

l)  ; 

echo 

5 

O 

U 

<jy 

:oi  .  " 

<- 

row\n" ; 

$row 

=  pg_ 

_f etch_ 

row 

($result, 

2) ; 

echo 

$row  | 

:n  ■  " 

<- 

row\n" ; 

?> 

P9_Fi6ldlSNull  (PHP  3,  PHP  4  >=  4.0.0) 

Comprueba  si  un  campo  es  NULO 

int  pg_f ieldisnull  (int  result_id,  int  row,  mixed  field) 


Comprueba  si  un  campo  vale  null  o  no.  Devuleve  0  si  el  campo  en  la  fila  dada  no  es  NULO  y  uno  en  el 
caso  de  que  lo  sea.  El  campo  se  puede  especificar  mediante  un  numero  o  un  nombre  de  campo.  La 
numeracion  de  filas  empieza  en  0. 


pg_FieldName  <php  3,  PHP  4  >=  4.0.0 

Devuelve  el  nombre  de  un  campo 

string  pg_f ieldname  (int  result_id,  int  field_number) 
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pg_FieldName()  devolvera  el  nombre  del  campo  que  ocupa  el  numero  de  columna  dado  en  el 
identificador  de  resultado  de  PostgreSQL.  La  numeracion  de  los  campos  empieza  con  0. 


pg_FieldNum  (php 3,  php 4 >=  4 .0 ,0) 


Devuelve  el  numero  de  una  columna 


int  pg_fieldnum  (int  result_id,  string  field_name) 


pg_FieldNum()  devolvera  el  numero  de  la  columna  que  corresponde  al  campo  cuyo  nombre  le  damos, 
dentro  del  identificador  de  resultado  de  PostgreSQL.  La  numeracion  de  campos  comienza  en  0.  Esta 
funcion  devolvera  -1  en  caso  de  error. 


pg_Field  PrtLen  (php  3,  php  4  >=  4.o.o) 


Devuelve  la  longitud  impresa 


int  pg_f ieldprtlen  (int  result_id,  int  row_number , 


string  field_name) 


pg_FieldPrtLen()  devolvera  la  longitud  impresa  real  (numero  de  caracteres)  de  un  valor  especffico 
dentro  del  identificador  de  resultado  PostgreSQL.  La  numeracion  de  filas  comienza  en  0.  Esta  funcion 
devolvera  - 1  en  caso  de  error. 


pg_FieldSize  (PHP  3,  PHP  4  >=  4.0.0) 

Devuelve  el  tamano  de  almacenamiento  interno  de  un  campo  en  concreto 

int  pg_fieldsize  (int  result_id,  int  field_number ) 


pg_FieldSize()  devolvera  el  tamano  de  almacenamiento  interno  (en  bytes)  de  uno  de  los  campos  del 
resultado  PostgreSQL  que  le  hemos  pasado.  La  numeracion  de  campos  empieza  en  0.  Un  tamano  de 
campo  de  -1  indica  que  se  trata  de  un  campo  de  longitud  variable.  La  funcion  devolvera  false  en  caso 
de  error. 
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pg_FieldType  (PHP  3,  PHP  4  >=  4.0.0) 

Devuelve  el  nombre  del  tipo  de  dato  correspondiente  al  campo  cuyo  numero  pasamos  como  parametro 

int  pg_fieldtype  (int  result_id,  int  field_number) 


pg_FieldType()  devolvera  una  cadena  con  el  nombre  del  tipo  de  datos  de  un  campo  dado  dentro  del 
identificador  de  resultado  PostgreSQL  result_id.  La  numeration  de  campos  empieza  en  0. 


pg_FreeResult  <php  3,  php  4  >=  4  o  0) 

Libera  memoria 

int  pg_freeresult  (int  result_id) 


pg_FreeResult()  solo  necesita  ser  llamada  si  estamos  preocupados  por  usar  demasiada  memoria 
mientras  el  script  se  esta  ejecutando.  La  memoria  correspondiente  a  todos  los  resultados  de  consulta  se 
libera  automaticamente  cuando  termina  el  script.  Pero,  si  estas  seguro  de  que  no  vas  a  necesitar  mas  los 
datos  del  resultado  en  el  script,  puedes  llamar  a  pg_FreeResult()  con  el  identificador  del  resultado  como 
parametro  y  la  memoria  asociada  al  resultado  sera  liberada. 


pg_GetLastOid  (php  3,  php  4  >=  4  o  o> 

Devuelve  el  identificador  del  ultimo  objeto  insertado 

int  pg_getlastoid  (int  result_id) 


pg_GetLastOid()  se  puede  usar  para  conseguir  el  Oid  (identificador  de  objeto)  asignado  a  una  tupla 
insertada  si  el  identificador  de  resultado  proviene  de  una  llamada  a  pg_Exec()  que  fuese  un  INSERT 
SQL.  Esta  funcion  devuelve  un  entero  positivo  si  hay  un  Oid  valido  y  -1  en  caso  de  que  ocurriese  un 
error  durante  el  ultimo  comando  enviado  a  traves  de  la  funcion  pg_Exec()  o  si  esta  no  fuese  un  INSERT. 


pg_Host  (PHP  3,  PHP  4  >=4.0.0) 

Devuelve  el  nombre  del  host 
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string  pg_host  (int  connect ion_id) 


pg_Host()  devuelve  el  nombre  del  host  al  que  identificador  conexion  PostgreSQL  pasado  esta  conectado. 


pgjoclose  (PHP  3,  PHP  4  >=  4.0.0) 

Cierra  un  objeto  grande  (large  object) 

void  pg_loclose  (int  fd) 


pg_loclose()  cierra  un  Large  Object,  fd  es  el  descriptor  de  fichero  del  fichero  grande  obtenido  a  traves 
de  pg_loopen 


pgjocreate  (PHP  3,  PHP  4  >=4.0.0) 


Crea  un  objeto  grande 


int  pg_locreate  (int  conn) 


pg_locreate()  Crea  un  Large  Object  y  devuelve  su  oid.  conn  determina  una  conexion  de  base  de  datos 
valida.  Los  modos  de  acceso  INV_READ,  INV_WRITE,  y  INV_ARCHIVE  de  PostgreSQL  no  estan 
soportados,  el  objeto  se  crea  siempre  con  acceso  tanto  de  lectura  como  de  escritura.  modo  El 
INV_ARCHIVE  ha  desaparecido  incluso  de  PostgreSQL  mismo  (a  partir  de  la  version  6.3). 


pgjoopen  (PHP  3,  PHP  4  >=4.0.0) 


Abre  un  objeto  grande 


int  pg_loopen  (int  conn,  int  objoid,  string  mode) 


pg_loopen()  abre  un  Large  Object  (objeto  grande)  y  devuelve  un  descriptor  de  fichero  para  el  objeto 
grande.  El  descriptor  de  fichero  encapsula  informacion  acerca  de  la  conexion.  No  se  debe  cerrar  la 
conexion  antes  de  cerrar  el  descriptor  de  fichero  al  objeto  grande,  objoid  especifica  un  oid  valido  para 
un  objeto  grande  y  mode  puede  ser  "r",  "w",  o  "rw". 
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pgjoread  (PHP  3,  PHP  4  >=  4.0.0) 

lee  un  large  object  (objeto  grande) 

string  pg_loread  (int  fd,  int  len) 


pg_loread()  lee  como  mucho  len  bytes  a  partir  de  un  objeto  grande  y  lo  devuelve  como  una  cadena.  fd 
especifica  un  descriptor  de  fichero  de  objeto  grande  valido  y  len  especifica  maximo  numero  de  bytes 
que  se  deben  leer  del  objeto  grande. 


pgjoreadall  (PHP  3,  PHP  4  >=4.0.0) 

Lee  un  objeto  grande  entero 

void  pg_loreadall  (int  fd) 


pg_loreadall()  lee  un  objeto  grande  y  lo  pasa  tal  cual  al  browser  despues  de  enviar  todas  las  cabeceras 
pendientes.  Principalmente  dirijido  a  mandar  datos  binarios  como  imagenes  o  sonido. 


pgjounlink  (PHP  3,  PHP  4  >=4.0.0) 

borra  un  large  object 

void  pg_lounlink  (int  conn,  int  lobjld) 


pg_lounlink()  borra  el  objeto  grande  con  identificador  lobjld. 


pgjowrite  (PHP  3,  PHP  4  >=4.0.0) 

escribe  en  un  objeto  grande 

int  pg_lowrite  (int  fd,  string  buf ) 
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pg_lowrite()  escribe  todo  lo  que  puede  en  un  objeto  grande  a  partir  de  la  variable  buf  y  devuelve  el 
numero  de  bytes  realmente  escritos,  o  falso  si  ocurre  algun  error,  fd  es  un  descriptor  de  fichero  para  el 
objeto  grande  obtenido  a  traves  de  pg_loopen  '). 


pg  NumFields  (php 3,  php 4 >=  4.0.0) 

Devuelve  el  numero  de  campos 

int  pg_numfields  (int  result_id) 


pg_NumFields()  devuelve  el  numero  de  campos  (columnas)  en  un  resultado  PostgreSQL.  El  parametro 
es  un  identificador  de  resultado  valido  devuelto  por  pg_Exec().  La  funcion  devuelve  -1  en  caso  de  error. 


pgNumRows  (php 3,  php 4 >=  4.0.0 

Devuelve  el  numero  de  filas 

int  pg_numrows  (int  result_id) 


pg_NumRows()  devuelve  el  numero  de  filas  en  un  resultado  PostgreSQL.  El  parametro  es  un 
identificador  de  resultado  PostgreSQL  valido  devuelto  por  pg_Exec().  En  caso  de  error  se  devuelve  -1. 


P9_Options  (PHP  3,  PHP  4  >=4.0.0) 

Devuelve  opciones 

string  pg_options  (int  connect ion_id) 


Pg_Options()  devuelve  una  cadena  que  contiene  las  opciones  especificadas  en  el  identificador  de 
conexion  con  PostgreSQL  dado. 


pg_pConnect  (PHP  3,  PHP  4  >=  4.0.0) 

Crea  una  conexion  persistente  con  una  base  de  datos 
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int  pq  pconnect  (string  host,  string  port,  string  options ,  string  tty,  string 
dhn ame) 


Devuelve  un  rndice  de  conexion  en  caso  de  exito,  o  false  si  no  es  posible  realizar  la  conexion.  Abre  una 
conexion  persistente  hacia  una  base  de  datos  de  PostgreSQL.  Cada  uno  de  los  parametros  puede  ser  una 
cadena  entrecomillada  (quoted),  incluyendo  el  numero  de  puerto.  Los  parametros  options  y  tty  son 
opcionales  y  pueden  omitirse.  Esta  funcion  devuelve  un  rndice  de  conexion  que  luego  sera  empleado  al 
llamar  a  otras  funciones  PostgreSQL.  Puedes  tener  multiples  conexiones  persistentes  abiertas  al  mismo 
tiempo.  Ver  tambien  pg_Connect(). 

Una  conexion  tambien  se  puede  establecer  con  el  comando  siguiente:  $conn  = 
pg_pconnect("dbname=marliese  port=5432");  Otros  parametros  ademas  de  dbname  y  port  son 
host,  tty,  options,  user  y  password. 


pg_Port  (PHP  3,  PHP  4  >=  4.0.0) 

Devuelve  el  numero  de  puerto 

int  pg_port  (int  connect ion_id) 


pg_Port()  devuelve  el  numero  del  puerto  al  que  el  identificador  de  conexion  con  PostgreSQL  esta 
conectado. 


pg_Result  (PHP  3,  PHP  4  >=4.0.0) 

Devuelve  valores  a  partir  de  un  identificador  de  resultado 

mixed  pg_result  (int  result_id,  int  row_number ,  mixed  fieldname) 


pg_Result()  devuelve  valores  a  partir  de  un  identificador  de  resultado  generado  en  la  funcion  pg_Exec(). 
Los  parametros  row_number  y  fieldname  especifican  que  celda  en  la  tabla  queremos  obtener.  La 
numeracion  de  filas  comienza  en  0.  En  vez  de  usar  el  nombre  del  campo  tambien  puedes  usar  el  rndice 
del  campo  como  un  numero  sin  entrecomillar.  Los  indices  de  campo  comienzan  tambien  en  0. 

PostgreSQL  tiene  muchos  tipos  y  solo  los  basicos  estan  soportados  directamente  aqui.  Todas  las  formas 
de  enteros,  boleanos  y  oids  se  devuelven  como  valores  enteros.  Todas  las  formas  de  los  tipos  float  y  real 
se  devuelven  como  valores  double.  Todos  los  demas  tipos,  incluyendo  los  arrays  se  devuelven  como 
cadenas  formateadas  de  la  misma  manera  en  que  PostgreSQL  usa  por  defecto.  De  la  misma  forma  en  que 
lo  verias  en  el  programa  psql. 
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pg_tty  (PHP  3,  PHP  4  >=  4.0.0) 

Devuelve  el  nombre  del  tty 

string  pg_tty  (int  connect ion_id) 


pg_tty()  devuelve  el  nombre  del  tty  hacia  el  que  se  dirije  la  salida  de  depuracion  del  lado  del  servidor  en 
el  identificador  de  conexion  de  PostgreSQL  dado. 
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escapeshellcmd  (php 3,  php 4 >=  4 .0 ,0) 


Ejecucion  de  programas 


enmascara  los  metacaracteres  del  interprete  de  ordenes 


string  escapeshellcmd  (string  command) 


EscapeShellCmdO  enmascara  cualquier  caracter  en  una  cadena  de  caracteres  que  pueda  usarse  para 
introducir  fraudulentamente  una  orden  al  interprete  de  ordenes  para  que  este  ejecute  instrucciones 
arbitrarias.  Esta  funcion  se  deberfa  usar  para  asegurarse  que  cualquier  dato  que  venga  del  usuario  se 
enmascare  antes  de  que  este  se  le  pase  a  las  funciones  exec  ')  o  system'),  o  al  operador  ‘  (apostrofe 
invertido) .  Un  uso  habitual  podrfa  ser: 


system (EscapeShellCmd ( $cmd) ) 


Vease  tambien  exec)),  popcn  ),  system)),  y  el  operador  ‘  (apostrofe  invertido) 


exec  (PHP  3,  PHP  4  >=4.0.0) 

Ejecuta  un  programa  externo 

string  exec  (string  command  [,  string  array  [,  int  return_var] ] ) 


exec()  ejecuta  la  orden  indicada  en  command ,  sin  embargo  no  produce  ninguna  salida.  Simplemente 
devuelve  la  ultima  lrnea  de  la  salida  resultado  de  la  orden.  Si  necesita  ejecutar  una  orden  y  obtener 
directamente  todos  los  datos  devueltos  por  la  orden  sin  ninguna  interferencia,  use  la  funcion  PassThru(). 

Si  el  parametro  array  existe,  entonces  el  array  especificado  se  rellenara  con  cada  una  de  las  lfneas  de  la 
salida  producida  por  la  orden.  Notar  que  si  el  array  ya  contiene  algunos  elementos,  exec()  los  anadira  al 
final  del  array.  Si  no  quiere  que  la  funcion  anada  dichos  elementos,  haga  un  unset))  sobre  el  array  antes 
de  pasarselo  a  exec(). 

Si  el  parametro  return_var  existe  a  la  vez  que  el  parametro  array,  entonces  el  valor  de  retorno  de 
la  orden  ejecutada  se  guardara  en  dicha  variable. 

Destacar  que  si  usted  va  a  permitir  que  se  pasen  datos  provenientes  de  usuarios  a  esta  funcion,  entonces 
deberfa  usar  EscapeShellCmdO  para  asegurarse  de  que  los  usuarios  no  pueden  enganar  al  sistema  para 
ejecutar  instrucciones  arbitrarias. 

Vease  tambien  system)),  PassThruQ,  popenj),  EscapeShellCmdO,  y  el  operador  ‘  (apostrofe  invertido) 
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passthru  (PHP  3,  PHP  4  >=  4.0.0) 


Ejecucion  de  programas 


Ejecuta  un  programa  externo  y  muestra  su  salida  literal 

string  passthru  (string  command  [,  int  return_var] ) 


La  funcion  passthru()  es  similar  a  la  funcion  exec  ')  en  que  ejecuta  una  orden  (command).  Si  existe  el 
parametro  return_var,  el  valor  de  estado  devuelto  por  la  orden  Unix  se  guardara  ahf.  Esta  funcion 
deberfa  usarse  en  lugar  de  exec ))  o  system))  cuando  la  salida  de  la  orden  Unix  sean  datos  binarios  que 
deban  ser  pasados  directamente  al  navegador.  Un  uso  tfpico  de  ello  es  ejecutar  algo  como  las  utilidades 
pbmplus  las  cuales  pueden  dar  como  resultado  directamente  el  flujo  de  datos  de  una  imagen.  Poniendo  el 
content-type  a  image/gif  y  llamando  al  programa  pbmplus  para  mostrar  un  gif,  usted  puede  crear 
archivos  de  ordenes  PHP  que  generen  directamente  imagenes. 

Vease  tambien  exec)),  system)),  popen)),  EscapeShellCmd(),  y  el  operador  ‘  (apostrofe  invertido) 


system  (PHP  3,  PHP  4  >=  4.0.0) 

Ejecuta  un  programa  externo  y  muestra  su  salida 

string  system  (string  command  [,  int  return_var]) 


system))  se  parece  a  la  version  C  de  la  funcion  de  mismo  nombre  en  que  ejecuta  la  orden  indicada  en 
command  y  muestra  el  resultado.  Si  se  indica  una  variable  como  segundo  parametro,  el  codigo  de  estado 
devuelto  por  la  orden  ejecutada  se  guardara  en  esta  variable. 

Destacar  que  si  usted  va  a  permitir  que  se  pasen  datos  provenientes  de  usuarios  a  esta  funcion,  entonces 
deberfa  usar  EscapeShellCmd()  para  asegurarse  de  que  los  usuarios  no  pueden  enganar  al  sistema  para 
ejecutar  instrucciones  arbitrarias. 

La  llamada  a  system))  tambien  intenta  vaciar  automaticamente  el  buffer  de  salida  del  servidor  web 
despues  de  cada  lfnea  de  salida  si  PHP  esta  funcionando  como  un  modulo  del  servidor. 

Devuelve  la  ultima  lfnea  de  la  orden  en  caso  de  exito,  y  falso  en  caso  de  fallo. 

Si  necesita  ejecutar  una  orden  y  obtener  de  vuelta  todo  los  datos  del  mismo  sin  interferencias,  use  la 
funcion  PassThru)). 

Vease  tambien  exec)),  PassThru)),  popen)),  EscapeShellCmd)),  y  el  operador  ‘  (apostrofe  invertido) 
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LXIX.  Printer  functions 


These  functions  are  only  available  under  Windows  9.x,  ME,  NT4  and  2000.  They  have  been  added  in 
PHP  4  (4.0.4). 
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Printer 


Open  connection  to  a  printer 


mixed  printer_open  ([string  devicename ]) 


This  function  tries  to  open  a  connection  to  the  printer  devicename,  and  returns  a  handle  on  success  or 
false  on  failure. 

If  no  parameter  was  given  it  tries  to  open  a  connection  to  the  default  printer  (if  not  specified  in  php  .ini 
as  printer .  def ault_printer,  php  tries  to  detect  it). 

printer_open()  also  starts  a  device  context. 

Ejemplo  1.  printer_open()  example 

$handle  =  printer_open ( "HP  Desk jet  930c"); 

$handle  =  printer_open ( ) ; 


printer_abort  (php  4  >=  4.0.6) 


Deletes  the  printer’s  spool  file 


void  printer_abort  (resource  handle) 


This  function  deletes  the  printers  spool  file. 
handle  must  be  a  valid  handle  to  a  printer. 

Ejemplo  1.  printer_abort()  example 

$handle  =  printer_open ( ) ; 
printer_abort ($handle) ; 
printer_close ($handle) ; 


printerclose  (php  4  >=  4  0  4) 


Close  an  open  printer  connection 
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void  printer_close  (resource  handle) 


This  function  closes  the  printer  connection.  printer_close()  also  closes  the  active  device  context. 
handle  must  be  a  valid  handle  to  a  printer. 

Ejemplo  1.  printer_close()  example 

$handle  =  printer_open ( ) ; 
printer_close ($handle) ; 


printerwrite  (PHP  4  >=  4.0.4) 


Write  data  to  the  printer 


bool  printer_write  (resource  handle,  string  content ) 


Writes  content  directly  to  the  printer,  and  returns  true  on  success  or  false  if  it  failed. 
handle  must  be  a  valid  handle  to  a  printer. 

Ejemplo  1.  printer_write()  example 

$handle  =  printer_open ( ) ; 
printer_write ( $handle,  "Text  to  print"); 
printer_close ( $handle) ; 


printer_list(PHP4>=4  0  4) 


Return  an  array  of  printers  attached  to  the  server 


array  printer_list  (int  enumtype  [,  string  name  [,  int  level]]) 


The  function  enumerates  available  printers  and  their  capabilities,  level  sets  the  level  of  information 
request.  Can  be  1,2,4  or  5.  enumtype  must  be  one  of  the  following  predefined  constants: 

•  PRINTER_ENUM_LOCAL:  enumerates  the  locally  installed  printers. 

•  PRINTER_ENUM_NAME:  enumerates  the  printer  of  name,  can  be  a  server,  domain  or  print  provider. 
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•  PRINTER_ENUM_SHARED:  this  parameter  can’t  be  used  alone,  it  has  to  be  OR’ed  with  other 
parameters,  i.e.  PRINTER_ENUM_LOCAL  to  detect  the  locally  shared  printers. 

•  PRINTER_ENUM_DEFAULT:  (Win9.x  only)  enumerates  the  default  printer. 

•  PRINTER_ENUM_CONNECTIONS :  (WinNT/2000  only)  enumerates  the  printers  to  which  the  user 
has  made  connections. 

•  PRINTER_ENUM_NETWORK:  (WinNT/2000  only)  enumerates  network  printers  in  the  computer’s 
domain.  Only  valid  if  level  is  1. 

•  PRINTER_ENUM_REMOTE :  (WinNT/2000  only)  enumerates  network  printers  and  print  servers  in 
the  computer’s  domain.  Only  valid  if  level  is  1. 


Ejemplo  1.  printer_list()  example 

/*  detect  locally  shared  printer  */ 

var_dump (  printer_list (PRINTER_ENUM_LOCAL  |  PRINTER_ENUM_SHARED )  ); 


printer_set_option  (PHP  4  >=  4.0.4) 

Configure  the  printer  connection 

bool  printer_set_option  (resource  handle,  int  option,  mixed  value) 


The  function  sets  the  following  options  for  the  current  connection:  handle  must  be  a  valid  handle  to  a 
printer.  For  option  can  be  one  of  the  following  constants: 

•  PRINTER_COP IES:  sets  how  many  copies  should  be  printed,  val  ue  must  be  an  integer. 

•  PRINTER_MODE :  specifies  the  type  of  data  (text,  raw  or  emf),  value  must  be  a  string. 

•  PRINTER_TITLE :  specifies  the  name  of  the  document,  value  must  be  a  string. 

•  PRINTER_ORIENTAT  ION :  specifies  the  orientation  of  the  paper,  value  can  be  either 
PRINTER_ORIENTATION_PORTRAIT  or  PRINTER_ORIENTATION_LANDSCAPE 

•  PRINTER_RESOLUTION_Y:  specifies  the  y-resolution  in  DPI,  value  must  be  an  integer. 

•  PRINTER_RESOLUTION_X:  specifies  the  x-resolution  in  DPI,  value  must  be  an  integer. 

•  PRINTER_PAPER_FORMAT :  specifies  the  a  predefined  paper  format,  set  value  to 
PRINTER_FORMAT_CUSTOM  if  you  want  to  specify  a  custom  format  with 
PRINTER_PAPER_WIDTH  and  PRINTER_PAPER_LEN  GTH .  value  can  be  one  of  the  following 
constants. 

•  PRINTER_FORMAT_CUSTOM :  let’s  you  specify  a  custom  paper  format. 

•  PRINTER_FORMAT_LETTER\  specifies  standard  letter  format  (8  1/2-  by  11-inches). 
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•  PRINTER_FORMAT_LETTER:  specifies  standard  legal  format  (8  1/2-  by  14-inches). 

•  PRINTER_FORMAT_A3 :  specifies  standard  A3  format  (297-  by  420-millimeters). 

•  PRINTER_FORMAT_A4:  specifies  standard  A4  format  (210-  by  297-millimeters). 

•  PRINTER_FORMAT_A5 :  specifies  standard  A5  format  (148-  by  210-millimeters). 

•  PRINTER_FORMAT_B4:  specifies  standard  B4  format  (250-  by  354-millimeters). 

•  PRINTER_FORMAT_B5 :  specifies  standard  B5  format  (182-  by  257-millimeter). 

•  PRINTER_FORMAT_FOLIO:  specifies  standard  FOLIO  format  (8  1/2-  by  13-inch). 


•  PRINTER_PAPER_LENGTH:  if  PRINTER_PAPER_FORMAT  is  set  to 
PRINTER_FORMAT_CUSTOM,  PRINTER_PAPER_LENGTH  specifies  a  custom  paper  length  in 
mm,  value  must  be  an  integer. 

•  PR  INTER_PAPER_  WID  TH:  if  PRINTER_PAPER_FORMAT  is  set  to 
PRINTER_FORMAT_CUSTOM,  PRINTER_PAPER_WIDTH  specifies  a  custom  paper  width  in  mm, 
value  must  be  an  integer. 

•  PRINTER_SCALE:  specifies  the  factor  by  which  the  printed  output  is  to  be  scaled,  the  page  size  is 
scaled  from  the  physical  page  size  by  a  factor  of  scale/100,  for  example  if  you  set  the  scale  to  50,  the 
output  would  be  half  of  it’s  original  size,  value  must  be  an  integer. 

•  PRINTER_BACKGROUND_COLOR:  specifies  the  background  color  for  the  actual  device  context, 
val  ue  must  be  a  string  containing  the  rgb  information  in  hex  format  i.e.  "005533". 

•  PRINTER_TEXT_COLOR:  specifies  the  text  color  for  the  actual  device  context,  value  must  be  a 
string  containing  the  rgb  information  in  hex  format  i.e.  "005533". 

•  PRINTER_TEXT_ALIGN:  specifies  the  text  alignment  for  the  actual  device  context,  value  can  be 
combined  through  OR’ing  the  following  constants: 

•  PRINTER_TA_BASELINE:  text  will  be  aligned  at  the  base  line. 

•  PRINTER_TA_BOTTOM :  text  will  be  aligned  at  the  bottom. 

•  PRINTER_  TA_  TOP:  text  will  be  aligned  at  the  top. 

•  PRINTER_TA_CENTER :  text  will  be  aligned  at  the  center. 

•  PRINTER_  TA_LEFT:  text  will  be  aligned  at  the  left. 

•  PRINTER_  TA_RIGHT:  text  will  be  aligned  at  the  right. 


Ejemplo  1.  printer_set_option()  example 

$handle  =  printer_open ( ) ; 

printer_set_option ( $handle,  PRINTER_SCALE,  75); 

printer_set_option ( $handle,  PRINTER_TEXT_ALIGN,  PRINTER_TA_LEFT ) ; 
printer_close ( $handle) ; 
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Printer 


Retrieve  printer  configuration  data 


mixed  printer_get_option  (resource  handle,  string  option) 


The  function  retrieves  the  configuration  setting  of  option,  handle  must  be  a  valid  handle  to  a  printer. 
Take  a  look  at  printer_set_option ')  for  the  settings  that  can  be  retrieved,  additionally  the  following 
settings  can  be  retrieved: 

•  PRINTER_DEVICENAME  returns  the  devicename  of  the  printer. 

•  PRINTER_DRIVERVERSION  returns  the  printer  driver  version. 


Ejemplo  1.  printer_get_option()  example 

$handle  =  printer_open ( ) ; 

print  printer_get_option ($handle,  PRINTER_DRIVERVERSION) ; 
printer_close ( $handle) ; 


printer_create_dc  (php  4  >=  4  o  4) 


Create  a  new  device  context 


void  printer_create_dc  (resource  handle) 


The  function  creates  a  new  device  context.  A  device  context  is  used  to  customize  the  graphic  objects  of 
the  document,  handle  must  be  a  valid  handle  to  a  printer. 

Ejemplo  1.  printer_create_dc()  example 

$handle  =  printer_open ( ) ; 
printer_start_doc ($handle) ; 
printer_start_page ($handle)  ; 

printer_create_dc ($handle)  ; 

/*  do  some  stuff  with  the  dc  */ 

printer_set_option ($handle,  PRINTER_TEXT_COLOR,  "333333"); 
printer_draw_text ($handle,  1,  1,  "text"); 
printer_delete_dc ($handle) ; 

/*  create  another  dc  */ 
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printer_create_dc ($handle) ; 

printer_set_option ( $handle,  PRINTER_TEXT_COLOR,  "000000"); 
printer_draw_text ($handle,  1,  1,  "text"); 

/*  do  some  stuff  with  the  dc  */ 

printer_delete_dc ($handle)  ; 

printer_endpage ($handle)  ; 
printer_end_doc ($handle)  ; 
printer_close ( $handle)  ; 


printer_delete_dc  (php  4  >=  4  o  4) 

Delete  a  device  context 

bool  printer_delete_dc  (resource  handle) 

The  function  deletes  the  device  context  and  returns  true  on  success,  or  false  if  an  error  occurred.  For 
an  example  see  printer_create_dc').  handle  must  be  a  valid  handle  to  a  printer. 


printer_start_doc  <php  4  >=  4  o  4> 


Start  a  new  document 


bool  printer_start_doc  (resource  handle  [,  string  document ]) 


The  function  creates  a  new  document  in  the  printer  spooler.  A  document  can  contain  multiple  pages,  it’s 
used  to  schedule  the  print  job  in  the  spooler,  handle  must  be  a  valid  handle  to  a  printer.  The  optional 
parameter  document  can  be  used  to  set  an  alternative  document  name. 

Ejemplo  1.  printer_start_doc()  example 

$handle  =  printer_open ( ) ; 

printer_start_doc ($handle,  "My  Document") ; 
printer_start_page ($handle)  ; 

printer_end_page (Shandle)  ; 
printer_end_doc ($handle)  ; 
printer_close ( $handle)  ; 
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printer_end_doc  (php  4  >=  4  o  4) 

Close  document 

bool  printer_end_doc  (resource  handle) 


Closes  a  new  document  in  the  printer  spooler.  The  document  is  now  ready  for  printing.  For  an  example 
see  printer_start_doc ').  handle  must  be  a  valid  handle  to  a  printer. 


printer_start_page  (PHP  4  >=4.0.4) 

Start  a  new  page 

bool  printer_start_page  (resource  handle) 


The  function  creates  a  new  page  in  the  active  document.  For  an  example  see  printer_start_docO- 
handle  must  be  a  valid  handle  to  a  printer. 


printer_end_page  (php  4  >=  4  o  4) 

Close  active  page 

bool  printer_end_page  (resource  handle) 


The  function  closes  the  active  page  in  the  active  document.  For  an  example  see  printer_start_docO- 
handle  must  be  a  valid  handle  to  a  printer. 


printer_create_pen  (PHP  4  >=  4.0.4) 

Create  a  new  pen 

mixed  printer  create  pen  (int  style,  int  width,  string  color) 
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The  function  creates  a  new  pen  and  returns  a  handle  to  it.  A  pen  is  used  to  draw  lines  and  curves.  For  an 
example  see  printer  select  pen ').  color  must  be  a  color  in  RGB  hex  format,  i.e.  "000000"  for  black, 
width  specifies  the  width  of  the  pen  whereas  style  must  be  one  of  the  following  constants: 

•  PRINTER_PEN_SOLID:  creates  a  solid  pen. 

•  PRINTER_PEN_DASH :  creates  a  dashed  pen. 

•  PRINTER_PEN_DOT:  creates  a  dotted  pen. 

•  PRINTER_PEN_DASHDOT :  creates  a  pen  with  dashes  and  dots. 

•  PRINTER_PEN_DASHDOTDOT :  creates  a  pen  with  dashes  and  double  dots. 

•  PRINTER_PEN_INVISIBLE:  creates  an  invisible  pen. 


printer_delete_pen  (php4>=4  0  4) 

Delete  a  pen 

bool  printer_delete_pen  (resource  handle) 


The  function  deletes  the  selected  pen.  For  an  example  see  printer_select_pen').  It  returns  true  on 
success,  or  false  otherwise,  handle  must  be  a  valid  handle  to  a  pen. 


printer_select_pen  (php4>=4.o.4) 


Select  a  pen 


void  printer  select  pen  (resource  printer_handle ,  resource  pen_handle) 


The  function  selects  a  pen  as  the  active  drawing  object  of  the  actual  device  context.  A  pen  is  used  to  draw 
lines  and  curves.  I.e.  if  you  draw  a  single  line  the  pen  is  used.  If  you  draw  an  rectangle  the  pen  is  used  to 
draw  the  borders,  while  the  brush  is  used  to  fill  the  shape.  If  you  haven’t  selected  a  pen  before  drawing 
shapes,  the  shape  won’t  be  outlined.  printer_handle  must  be  a  valid  handle  to  a  printer. 
pen_handle  must  be  a  valid  handle  to  a  pen. 

Ejemplo  1.  printer_select_pen()  example 

$handle  =  printer_open ( ) ; 

printer_start_doc ($handle,  "My  Document") ; 
printer_start_page ($handle)  ; 
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$pen  =  printer_create_pen (PRINTER_PEN_SOLID,  30,  "2222FF"); 

printer_select_pen ( $handle,  $pen) ; 

printer_draw_line ($handle,  1,  60,  500,  60); 

printer_delete_pen ( $pen) ; 

printer_end_page ($handle)  ; 
printer_end_doc ($handle)  ; 
printer_close ( $handle)  ; 


printer_create_brush  (php  4  >=  4.o.4) 

Create  a  new  brush 


mixed  printer_create_brush  (int  style,  string  color) 


The  function  creates  a  new  brush  and  returns  a  handle  to  it.  A  brush  is  used  to  fill  shapes.  For  an  example 
see  printer  select  brush ').  color  must  be  a  color  in  RGB  hex  format,  i.e.  "000000"  for  black,  style 
must  be  one  of  the  following  constants: 

•  PRINTER_BRUSH_SOLID :  creates  a  brush  with  a  solid  color. 

•  PRINTER_BRUSH_D  I  AGONAL:  creates  a  brush  with  a  45-degree  upward  left-to-right  hatch  (  /  ). 

•  PRINTER_BRUSH_CROSS:  creates  a  brush  with  a  cross  hatch  (  +  ). 

•  PRINTER_BRUSH_DIAGCROSS:  creates  a  brush  with  a  45  cross  hatch  (  x  ). 

•  PRINTER_BRU SH_FD I AGONAL:  creates  a  brush  with  a  45-degree  downward  left-to-right  hatch  (  \ ). 

•  PRINTER_BRUSH_HORI ZONTAL:  creates  a  brash  with  a  horizontal  hatch  ( -  ). 

•  PR  INTER_BRUSH_  VER  T I  CAL:  creates  a  brush  with  a  vertical  hatch  (  I  ). 

•  PRINTER_BRUSH_CU STOM:  creates  a  custom  brush  from  an  BMP  file.  The  second  parameter  is 
used  to  specify  the  BMP  instead  of  the  RGB  color  code. 


printer_delete_brush  (php  4  >=  4 .0 ,4) 


Delete  a  brush 


bool  printer_delete_brush  (resource  handle) 
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The  function  deletes  the  selected  brush.  For  an  example  see  printer_select_brush  f).  It  returns  true  on 
success,  or  false  otherwise,  handle  must  be  a  valid  handle  to  a  brush. 


printer_select_brush  (php  4  >=  4.o.4> 


Select  a  brush 


void  printer_select_brush  (resource  prlnter_handle ,  resource  brush_handle ) 


The  function  selects  a  brush  as  the  active  drawing  object  of  the  actual  device  context.  A  brush  is  used  to 
fill  shapes.  If  you  draw  an  rectangle  the  brush  is  used  to  draw  the  shapes,  while  the  pen  is  used  to  draw 
the  border.  If  you  haven’t  selected  a  bmsh  before  drawing  shapes,  the  shape  won’t  be  filled. 
printer_handle  must  be  a  valid  handle  to  a  printer.  brush_handle  must  be  a  valid  handle  to  a 
brush. 

Ejemplo  1.  printer_select_brush()  example 

$handle  =  printer_open ( ) ; 

printer_start_doc ($handle,  "My  Document") ; 
printer_start_page ($handle) ; 

$pen  =  printer  create  pen (PRINTER  PEN  SOLID,  2,  "000000"); 

printer_select_pen ( $handle,  $pen)  ; 

$brush  =  printer_create_brush (PRINTER_BRUSH_CUSTOM,  "c : \\brush.bmp") ; 
printer_select_brush ( $handle ,  $brush) ; 

printer_draw_rect angle ( $handle,  1,1,500,500); 

printer_delete_brush ($brush)  ; 

$brush  =  printer_create_brush (PRINTER_BRUSH_SOLID,  "000000"); 
printer_select_brush ( $handle ,  $brush) ; 
printer_draw_rect angle ( $handle,  1,501,500,1001); 
printer_delete_brush ( $brush) ; 

printer_delete_pen ( $pen) ; 


printer_end_page ($handle)  ; 
printer_end_doc ( $handle )  ; 
printer_close ($handle)  ; 
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printer_create_font  <php  4  >=  4  .0 ,4) 


Create  a  new  font 


mixed  printer_create_f ont  (string  face,  int  height,  int  width,  int 
font_weight,  bool  italic,  bool  underline ,  bool  strikeout ,  int  orientaton) 

The  function  creates  a  new  font  and  returns  a  handle  to  it.  A  font  is  used  to  draw  text.  For  an  example  see 
printer_select_font').  face  must  be  a  string  specifying  the  font  face,  height  specifies  the  font  height, 
and  width  the  font  width.  The  font_weight  specifies  the  font  weight  (400  is  normal),  and  can  be 
one  of  the  following  predefined  constants. 

•  PRINTER_FW_THIN:  sets  the  font  weight  to  thin  (100). 

•  PRINTER_FW_ULTRALIGHT:  sets  the  font  weight  to  ultra  light  (200). 

•  PRINTER_FW_LIGHT:  sets  the  font  weight  to  light  (300). 

•  PRINTER_FW_NORMAL:  sets  the  font  weight  to  normal  (400). 

•  PRINTER_FW_MEDIUM:  sets  the  font  weight  to  medium  (500). 

•  PRINTER_FW_BOLD:  sets  the  font  weight  to  bold  (700). 

•  PRINTER_FW_ULTRABOLD:  sets  the  font  weight  to  ultra  bold  (800). 

•  PR  INTER_FW_HEA  VY :  sets  the  font  weight  to  heavy  (900). 


italic  can  be  true  or  false,  and  sets  whether  the  font  should  be  italic. 
underline  can  be  true  or  false,  and  sets  whether  the  font  should  be  underlined. 
strikeout  can  be  true  or  false,  and  sets  whether  the  font  should  be  striked  out. 
orientation  specifies  a  rotation.  For  an  example  see  printer_select_fontO. 


printer_delete_font  <php  a  >=  4 .0 ,4) 

Delete  a  font 

bool  printer_delete_font  (resource  handle) 

The  function  deletes  the  selected  font.  For  an  example  see  printer  select  font  ).  It  returns  true  on 
success,  or  false  otherwise,  handle  must  be  a  valid  handle  to  a  font. 
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printer_select_font  (php  4  >=  4  .0 ,4) 


Select  a  font 


void  printer_select_font  (resource  printer_handle,  resource  font_handle) 


The  function  selects  a  font  to  draw  text,  print er_handle  must  be  a  valid  handle  to  a  printer. 
font_handle  must  be  a  valid  handle  to  a  font. 

Ejemplo  1.  printer_select_font()  example 

$handle  =  printer_open ( ) ; 

printer_start_doc ($handle,  "My  Document") ; 
printer_start_page ( $handle)  ; 

$font  =  printer_create_f ont ( "Arial " ,  148,  76,  PRINTER_FW_MEDIUM,  false,  false, 
50)  ; 

printer_select_f ont ($handle,  $font) ; 

printer_draw_text ($handle,  "PHP  is  simply  cool",  40,  40); 
printer_delete_f ont ($font)  ; 

printer_end_page ($handle)  ; 
printer_end_doc ( $handle )  ; 
printer_close ( $handle)  ; 


printer  Jogical_fontheight  <php  4  >=  4.o.4) 


Get  logical  font  height 


int  printer_logical_fontheight  (resource  handle,  int  height) 


The  function  calculates  the  logical  font  height  of  height,  handle  must  be  a  valid  handle  to  a  printer. 

Ejemplo  1.  printer_logical_fontheight()  example 

$handle  =  printer_open ( ) ; 

print  printer_logical_f ontheight ( $handle,  72); 
printer_close ($handle) ; 


false,  - 
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pri  nterd  rawrou  nd  rect  (php  4  >=  4.o.4) 


Draw  a  rectangle  with  rounded  corners 


void  printer_draw_roundrect  (resource  handle,  int  ul_x,  int  ul_y ,  int  lr_x, 
int  lr_y,  int  width,  int  height) 


The  function  simply  draws  a  rectangle  with  rounded  corners. 
handle  must  be  a  valid  handle  to  a  printer. 
ul_x  is  the  upper  left  x  coordinate  of  the  rectangle. 
ul_y  is  the  upper  left  y  coordinate  of  the  rectangle. 
lr_x  is  the  lower  right  x  coordinate  of  the  rectangle. 
lr_y  is  the  lower  right  y  coordinate  of  the  rectangle. 
width  is  the  width  of  the  ellipse. 
height  is  the  height  of  the  ellipse. 

Ejemplo  1.  printer_draw_roundrect()  example 

$handle  =  printer_open ( ) ; 

printer_start_doc ($handle,  "My  Document") ; 
printer_start_page ($handle) ; 

$pen  =  printer  create  pen (PRINTER  PEN  SOLID,  2,  "000000"); 

printer_select_pen ( $handle,  $pen) ; 

$brush  =  printer_create_brush (PRINTER_BRUSH_SOLID,  "2222FF"); 
printer_select_brush ( $handle,  $brush) ; 

printer_draw_roundrect ($handle,  1,  1,  500,  500,  200,  200); 

printer_delete_brush ( $brush)  ; 
printer_delete_pen ( $pen)  ; 

printer_end_page ($handle)  ; 
printer_end_doc ($handle)  ; 
printer_close ( $handle)  ; 


printerdrawrectangle  <php  4  >=  4.o.4) 


Draw  a  rectangle 
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void  printer_draw_rectangle  (resource  handle,  int  ul_x,  int  ul_y ,  int  lr_x, 
i  nt  i  r_y ) 


The  function  simply  draws  a  rectangle. 
handle  must  be  a  valid  handle  to  a  printer. 
ul_x  is  the  upper  left  x  coordinate  of  the  rectangle. 
ul_y  is  the  upper  left  y  coordinate  of  the  rectangle. 
lr_x  is  the  lower  right  x  coordinate  of  the  rectangle. 
lr_y  is  the  lower  right  y  coordinate  of  the  rectangle. 

Ejemplo  1.  printer_draw_rectangle()  example 

$handle  =  printer_open ( ) ; 

printer_start_doc ($handle,  "My  Document") ; 
printer_start_page ($handle) ; 

$pen  =  printer  create  pen (PRINTER  PEN  SOLID,  2,  "000000"); 

printer_select_pen ( $handle,  $pen) ; 

$brush  =  printer_create_brush (PRINTER_BRUSH_SOLID,  "2222FF"); 
printer_select_brush ($handle,  $brush) ; 

printer_draw_rectangle ($handle,  1,  1,  500,  500); 

printer_delete_brush ($brush) ; 
printer_delete_pen ( $pen) ; 

printer_end_page ($handle)  ; 
printer_end_doc ($handle)  ; 
printer_close ( $handle)  ; 


printer_draw_elipse(PHP4>=4  0  4) 


Draw  an  ellipse 


void  printer_draw_elipse  (resource  handle,  int  ul_x ,  int  ul_y ,  int  lr_x,  int 
lr_y) 


The  function  simply  draws  an  ellipse,  handle  must  be  a  valid  handle  to  a  printer. 
ul_x  is  the  upper  left  x  coordinate  of  the  ellipse. 
ul_y  is  the  upper  left  y  coordinate  of  the  ellipse. 
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lr_x  is  the  lower  right  x  coordinate  of  the  ellipse. 
lr_y  is  the  lower  right  y  coordinate  of  the  ellipse. 

Ejemplo  1.  printer_draw_elipse()  example 

$handle  =  printer_open ( ) ; 

printer_start_doc ($handle,  "My  Document") ; 
printer_start_page ($handle) ; 

$pen  =  printer  create  pen (PRINTER  PEN  SOLID,  2,  "000000"); 

printer_select_pen ( $handle,  $pen)  ; 

$brush  =  pr inter_create_brush (PRINTER_BRUSH_SOLID ,  "2222FF"); 

printer_select_brush ($handle,  $brush) ; 

printer_draw_elipse ($handle,  1,  1,  500,  500); 

printer_delete_brush ( $brush) ; 
printer_delete_pen ( $pen) ; 

printer_end_page ($handle)  ; 
printer_end_doc ($handle)  ; 
printer_close ($handle)  ; 


pri  nterd  rawtext  (php  4  >=  4 .0 ,4) 


Draw  text 


void  printer_draw_text  (resource  printer_handle,  string  text,  int  x,  int  y) 


The  function  simply  draws  text  at  position  x,  y  using  the  selected  font.  printer_handle  must  be  a 
valid  handle  to  a  printer. 

Ejemplo  1.  printer_draw_text()  example 

$handle  =  printer_open ( ) ; 

printer_start_doc ($handle,  "My  Document") ; 
printer_start_page ($handle) ; 

$f ont  =  printer_create_f ont ( "Arial " ,  72, 48,  400,  false,  false,  false,  0)  ; 
printer_select_f ont ($handle,  $font) ; 
printer_draw_text ($handle,  "test",  10,  10); 
printer_delete_f ont ($font)  ; 

printer_end_page ($handle)  ; 
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printer_end_doc ($handle)  ; 
printer_close ( $handle)  ; 


printer_draw_line(PHP4>=4  0  6) 


Draw  a  line 


void  printer_draw_line  (resource  printer_handle ,  int  from_x,  int  from_y,  int 
to_x,  int  to_y) 


The  function  simply  draws  a  line  from  position  from_x,  from_y  to  position  to_x,  to_y  using  the 
selected  pen.  printer_handle  must  be  a  valid  handle  to  a  printer. 

Ejemplo  1.  printer_draw_line()  example 

$handle  =  printer_open ( ) ; 

printer_start_doc ($handle,  "My  Document") ; 
printer_start_page ($handle) ; 

$pen  =  printer  create  pen (PRINTER  PEN  SOLID,  30,  "000000"); 

printer_select_pen ( $handle,  $pen) ; 

printer_draw_line ($handle,  1,  10,  1000,  10); 
printer_draw_line ($handle,  1,  60,  500,  60); 

printer_delete_pen ( $pen) ; 

printer_end_page ($handle)  ; 
printer_end_doc ($handle)  ; 
printer_close ( $handle)  ; 


printerdrawchord  (php4>=4  0  6) 


Draw  a  chord 


void  printer_draw_chord  (resource  handle,  int  rec_x ,  int  rec_y ,  int  rec_xl, 
int  rec_yl,  int  rad_x,  int  rad_y ,  int  rad_xl,  int  rad_yl ) 


The  function  simply  draws  an  chord,  handle  must  be  a  valid  handle  to  a  printer. 
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rec_x  is  the  upper  left  x  coordinate  of  the  bounding  rectangle. 
rec_y  is  the  upper  left  y  coordinate  of  the  bounding  rectangle. 
rec_xl  is  the  lower  right  x  coordinate  of  the  bounding  rectangle. 
rec_yl  is  the  lower  right  y  coordinate  of  the  bounding  rectangle. 
rad_x  is  x  coordinate  of  the  radial  defining  the  beginning  of  the  chord. 
rad_y  is  y  coordinate  of  the  radial  defining  the  beginning  of  the  chord. 
rad_xl  is  x  coordinate  of  the  radial  defining  the  end  of  the  chord. 
rad_yl  is  y  coordinate  of  the  radial  defining  the  end  of  the  chord. 

Ejemplo  1.  printer_draw_chord()  example 

$handle  =  printer_open ( ) ; 

printer_start_doc ($handle,  "My  Document") ; 
printer_start_page ($handle) ; 

$pen  =  printer  create  pen (PRINTER  PEN  SOLID,  2,  "000000"); 

printer_select_pen ( $handle,  $pen)  ; 

$brush  =  pr inter_create_brush (PRINTER_BRUSH_SOLID ,  "2222FF"); 

printer_select_brush ( $handle,  $brush) ; 

printer_draw_chord ( $handle,  1,  1,  500,  500,  1,  1,  500,  1); 

printer_delete_brush ( $brush) ; 
printer_delete_pen ( $pen) ; 

printer_end_page ($handle)  ; 
printer_end_doc ($handle)  ; 
printer_close ( $handle)  ; 


printer_draw_pie  (php  4  >=  4.0.6) 


Draw  a  pie 


void  printer  draw  pie  (resource  handle,  int  rec_x,  int  rec_y ,  int  rec_xl,  int 
rec_yl,  int  radl_x,  int  radl_y ,  int  rad2_x,  int  rad2_y) 


The  function  simply  draws  an  pie.  handle  must  be  a  valid  handle  to  a  printer. 
rec_x  is  the  upper  left  x  coordinate  of  the  bounding  rectangle. 
rec_y  is  the  upper  left  y  coordinate  of  the  bounding  rectangle. 
rec_xl  is  the  lower  right  x  coordinate  of  the  bounding  rectangle. 
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rec_yl  is  the  lower  right  y  coordinate  of  the  bounding  rectangle. 
radl_x  is  x  coordinate  of  the  first  radial’s  ending. 
radl_y  is  y  coordinate  of  the  first  radial’s  ending. 
rad2_x  is  x  coordinate  of  the  second  radial’s  ending. 
rad2_y  is  y  coordinate  of  the  second  radial’s  ending. 

Ejemplo  1.  pr  in  ter_dr  a vv  c h o r d  )  example 

$handle  =  printer_open ( ) ; 

printer_start_doc ($handle,  "My  Document") ; 
printer_start_page ($handle) ; 

$pen  =  printer  create  pen (PRINTER  PEN  SOLID,  2,  "000000"); 

printer_select_pen ( $handle,  $pen)  ; 

$brush  =  pr inter_create_brush (PRINTER_BRUSH_SOLID ,  "2222FF"); 

printer_select_brush ($handle,  $brush) ; 

printer_draw_pie (Shandle,  1,  1,  500,  500,  1,  1,  500,  1); 

printer_delete_brush ( $brush)  ; 
printer_delete_pen ( $pen) ; 

printer_end_page ($handle)  ; 
printer_end_doc ( $handle )  ; 
printer_close ( $handle)  ; 


printer_draw_bmp  (php  4  >=  4.0.6) 


Draw  a  bmp 


void  printer_draw_bmp  (resource  handle,  string  filename ,  int  x,  int  y) 


The  function  simply  draws  an  bmp  the  bitmap  filename  at  position  x,  y.  handle  must  be  a  valid 
handle  to  a  printer. 

The  function  returns  true  on  success,  or  otherwise  false. 

Ejemplo  1.  printer_draw_bmp()  example 

$handle  =  printer_open ( ) ; 

printer_start_doc ($handle,  "My  Document") ; 
printer_start_page ($handle) ; 
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printer_draw_bmp ($handle,  "c : \\ image .bmp" ,  1,  1) ; 

printer_end_page ($handle) ; 
printer_end_doc ($handle) ; 
printer_close ($handle) ; 


970 


LXX.  Pspell  Functions 

The  pspell()  functions  allow  you  to  check  the  spelling  of  a  word  and  offer  suggestions. 

You  need  the  aspell  and  pspell  libraries,  available  from  http://aspell.sourceforge.net/  and 
http://pspell.sourceforge.net/respectively,  and  add  the  — with-pspell  [=dir]  option  when  compiling 
php. 
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pspell_new  (php  4  >=  4.0.2) 


Load  a  new  dictionary 


int  pspell_new  (string  language,  string  [spelling], 
[encoding] ,  int  [mode]) 


string  [jargon] ,  string 


pspell_new()  opens  up  a  new  dictionary  and  returns  the  dictionary  link  identifier  for  use  in  other  pspell 
functions. 

The  language  parameter  is  the  language  code  which  consists  of  the  two  letter  ISO  639  language  code  and 
an  optional  two  letter  ISO  3166  country  code  after  a  dash  or  underscore. 

The  spelling  parameter  is  the  requested  spelling  for  languages  with  more  than  one  spelling  such  as 
English.  Known  values  are  ’american’,  ’british’,  and  ’Canadian’. 

The  jargon  parameter  contains  extra  information  to  distinguish  two  different  words  lists  that  have  the 
same  language  and  spelling  parameters. 

The  encoding  parameter  is  the  encoding  that  words  are  expected  to  be  in.  Valid  values  are  ’utf-8’, 
’iso8859-*\  ’koi8-r’,  ’viscii’,  ’cpl252’,  ’machine  unsigned  16’,  ’machine  unsigned  32’.  This  parameter 
is  largely  untested,  so  be  careful  when  using. 

The  mode  parameter  is  the  mode  in  which  spellchecker  will  work.  There  are  several  modes  available: 

•  PSPELL_FAST  -  Fast  mode  (least  number  of  suggestions) 

•  PSPELL_NORMAL  -  Normal  mode  (more  suggestions) 

•  PSPELL_BAD_SPELLERS  -  Slow  mode  (a  lot  of  suggestions) 

•  PSPELL_RUN_TOGETHER  -  Consider  run-together  words  as  legal  compounds.  That  is,  "thecat" 
will  be  a  legal  compound,  athough  there  should  be  a  space  between  the  two  words.  Changing  this 
setting  only  affects  the  results  returned  by  pspell  check ');  pspell_suggest'j  will  still  return 
suggestions. 

Mode  is  a  bitmask  constructed  from  different  constants  listed  above.  However,  PSPELL_FAST, 
PSPELL_NORMAL  and  PSPELL_BAD_SPELLERS  are  mutually  exclusive,  so  you  should  select  only 
one  of  them. 

For  more  information  and  examples,  check  out  inline  manual  pspell 
website:http://pspell.  sourceforge.net/. 


Ejemplo  1.  pspell_new() 

$pspell_link  =  pspell_new  ("en", 

(PSPELL_FAST | PSPELL_RUN_TOGETHER) ) ; 
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pspell_check  (php  4  >=  4.0.2) 


Pspell 


Check  a  word 


boolean  pspell_check  (int  dictionary_link ,  string  word) 


pspell_check()  checks  the  spelling  of  a  word  and  returns  true  if  the  spelling  is  correct,  false  if  not. 


Ejemplo  1.  pspell_check() 

$pspell_link  =  pspell_new  ("en") ; 

if  (pspell_check  ( $pspell_link,  "testt"))  { 
echo  "This  is  a  valid  spelling"; 

}  else  { 

echo  "Sorry,  wrong  spelling"; 

} 


pspell_suggest  <php  4  >=  4.0.2) 


Suggest  spellings  of  a  word 


array  pspell_suggest  (int  dictionary_link ,  string  word ) 


pspell_suggest()  returns  an  array  of  possible  spellings  for  the  given  word. 

Ejemplo  1.  pspell_suggest() 

$pspell_link  =  pspell_new  ("en") ; 

if  ( ! pspell_check  ( $pspell_link,  "testt"))  { 

Ssuggestions  =  pspell_suggest  ( $pspell_link,  "testt"); 

for  ($i=0;  $i  <  count  (Ssuggestions) ;  $i++)  { 

echo  "Possible  spelling:  "  .  $suggestions [ $i ]  .  "<br>"; 

} 


913 


LXXI.  GNU  Readline 


Las  funciones  readline')  implementan  una  interfaz  con  la  librerfa  GNU  Readline.  Un  ejemplo  de  la 
manera  de  funcionar  podrfa  ser  la  forma  en  que  el  Bash  permite  usar  las  flechas  de  direccion  para  insertar 
caracteres  o  desplazarse  a  traves  del  historial  de  comandos.  Debido  a  la  naturaleza  interactiva  de  esta 
libreria,  tendra  un  uso  muy  reducido  en  la  escritura  de  aplicaciones  Web,  aunque  puede  ser  util  para 
scripts  que  han  de  ser  ejecutados  desde  la  consola. 

La  pagina  principal  del  proyecto  GNU  Readline  es 

http://cnswww.cns.cwru.edu/~chet/readline/rltop.html.  Esta  actualizada  por  Chet  Ramey,  quien  ademas 
es  el  autor  de  Bash. 
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readline  (PHP  4  >=  4.0.0) 


Lee  una  lfnea 


string  readline  ([string  prompt ]) 


Esta  funcion  devuelve  una  unica  cadena  del  usuario.  Puede  especificar  una  cadena  que  se  mostrara  al 
usuario.  La  lfnea  devuelta  tiene  el  indicador  final  de  nueva  lfnea  eliminado.  Necesita  anadir  esta  lfnea  al 
historial  usando  la  funcion  readline_add_historyO- 

Ejemplo  1.  readlinef) 

//obtiene  3  comandos  del  usuario 
for  ($i=0 ;  $i  <  3;  $i++)  { 

$line  =  readline  ("Comando:  "); 
readline_add_history  ($line) ; 

} 

/ /Vuelca  el  historial 

print_r  ( readline_list_history ( ) ) ; 

/ /Vuelca  las  variables 
print_r  ( readline_inf o ( ) ) ; 


read  I  i  ne_add_h  istory  (php  4  >=  4.o.o> 

Anade  una  lfnea  al  historial 


void  readline_add_history  (string  line) 


Esta  funcion  anade  una  lfnea  al  historial  de  lfneas  de  comandos. 


readline_clear_history  (php  4  >=  4.0.o) 

Borra  el  historial 


boolean  readline_clear_history  (void  ) 
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Esta  funcion  borra  por  completo  el  historial  de  la  lmea  de  comandos. 


readline_completion_function(PHP4>=4  0  0) 

Registra  una  funcion  de  completitud 

boolean  readline_completion_function  (string  line) 


Esta  funcion  registra  una  funcion  de  completitud.  Debe  proporcionar  el  nombre  de  una  funcion  existente 
que  acepte  una  lfnea  de  comandos  parcial  y  devuelva  una  array  con  posibles  coincidencias.  Es  el  mismo 
tipo  de  funcionalidad  que  se  obtiene  al  pulsar  la  tecla  de  tabulacion  cuando  se  esta  usando  el  Bash. 


read  I  i  ne_i  nf  o  (php  4  >=  4.0.0 

Establece/Obtiene  diversas  variables  internas  de  readline 


mixed  readline_info  ([string  varname  [,  string  newvalue ]]) 


Si  es  llamada  sin  parametros,  esta  funcion  devuelve  un  array  con  los  valores  de  todas  las  opciones  que 
readline  usa.  Los  elementos  vendran  indexados  por  los  siguientes  valores:  done,  end,  erase_empty_line, 
library _version,  line_buffer,  mark,  pending_input,  point,  prompt,  readline_name,  y  terminal_name. 

Si  es  llamada  con  un  parametros,  devuelve  el  valor  de  esa  opcion.  Si  es  llamada  con  dos  parametros,  el 
valor  de  la  opcion  sera  cambiado  al  parametro  dado. 


read  I  i  nej  ist_h  istory  (php  4  >=  4.0.0 


Lista  el  historial 


array  readline_list_history  (void  ) 


Esta  funcion  devuelve  un  array  con  el  historial  de  lfneas  de  comandos  completo.  Los  elementos  estan 
indexados  por  enteros  comenzando  por  el  cero. 
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read  li  ne_read_h  istory  (php  4  >=  4.0.0) 

Lee  un  historial 


boolean  readline_read_history  (string  filename) 


Esta  funcion  lee  un  historial  de  comandos  desde  un  fichero. 


readline_write_history  {php  4  >=  4.o.o) 

Escribe  el  historial 


boolean  readline_write_history  (string  filename) 


Esta  funcion  escribe  el  historial  de  comandos  en  un  archivo. 
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LXXII.  Funciones  GNU  Recode 


Este  modulo  contiene  un  interfaz  para  la  biblioteca  GNU  Recode  version  3.5.  Para  poder  usar  las 
funciones  definidas  en  este  modulo,  debereis  de  compilar  el  interprete  PHP  con  la  opcion  — with-recode. 
Para  poder  hacer  esto  debereis  tener  instalado  en  vuestro  sistema  GNU  Recode  3.5  o  superior. 

La  biblioteca  GNU  Recode  convierte  entre  ficheros  con  diferentes  codigos  de  caracteres  y  codificacion. 
Cuando  esto  no  puede  realizarse  exactamente,  puede  desahacerse  de  los  caracteres  problematicos  o  crear 
una  aproximacion.  La  biblioteca  reconoce  o  produce  alrededor  de  150  codigos  de  caracteres  y  puede 
convertir  ficheros  entre  casi  todos  los  pares  posibles.  La  gran  mayoria  de  de  codigos  de  caracteres  RLC 
1345  estan  soportados. 
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recode_string  (PHP  3>=  3.0.13,  PHP  4  >=  4.0.0) 

Recodifica  una  cadena  literal  segun  una  peticion  de  recodificacion. 

string  recode_string  (string  request ,  string  string) 

Recodifica  la  cadena  string  segun  una  peticion  de  recodificacion  request.  Devuelve  false  si  no 
puede  realizar  la  recodificacion,  true  si  todo  va  bien. 

Una  simple  peticion  "recode"  podria  ser  "latl..iso646-de".  Ver  tambien  la  documentacion  de  GNU 
Recode  de  tu  instalacion  para  obtener  instrucciones  detalladas  sobre  peticiones  de  recodificacion. 

recode_file  (PHP  3>=  3.0.13,  PHP  4  >=  4.0.0) 

Recodifica  de  fichero  a  fichero  segun  una  peticion  de  recodificacion. 

bool  recode_file  (int  input,  int  output) 

Recodifica  el  fichero  definido  por  input  a  el  fichero  definido  por  output ,  segun  la  peticion  de 
recodificacion  request.  Devuelve  false  si  no  puede  realizar  la  recodificacion,  true  si  todo  va  bien. 

Esta  funcion  no  procesa  ficheros  remotos  (URLs).  Los  dos  ficheros  deben  de  ser  locales  en  el  sistema. 
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LXXIII.  Funciones  de  expresiones  regulares 
compatibles  con  Perl 

La  sintaxis,  para  los  patrones  usados  en  estas  funciones,  es  muy  semejante  al  Perl.  Las  expresiones 
estaran  encerradas  por  delimitadores,  por  ejemplo  una  barra  de  dividir  (/).  Cualquier  caracter  puede  ser 
usado  para  delimitar  incluso  los  que  no  son  caracteres  alfanumericos  o  la  barra  invertida  (\).  Si  el  caracter 
delimitador  ha  sido  usado  en  la  propia  expresion,  es  necesario  que  sea  precedido  por  una  barra  inversa. 

El  delimitador  de  fin  puede  ser  seguido  por  varios  modificadores  que  afectaran  al  resultado.  Examina 
Modificadores  de  Patrones 


Ejemplo  1.  Ejemplos  de  patrones  validos 


•  /<\Aw+>/ 

•  l(\d{3})-\d+ISm 

•  /A(?i)php[34]/ 


Ejemplo  2.  Ejemplos  de  patrones  no  validos 

•  /href='(-*)’  -  falta  el  delimitador  de  fin 

•  Aw+\s*\w+/J  -  el  modificador  ’J’  es  desconocido 

•  l-\d3-\d3-\d4l  -  falta  el  delimitador  de  inicio 


Nota:  Para  las  funciones  de  expresiones  compatibles  con  Perl  se  necesita  PHP  4  o  PHP  3.0.9  o 
superior. 
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preg_match  (PHP  3>=  3.0.9,  PHP  4  >=  4.0.0) 

Realiza  un  emparejamiento  dada  una  expresion 

int  preg_match  (string  pattern,  string  subject  [,  array  matches ]) 


Busca  en  subject  para  un  emparejamiento,  dada  la  expresion  pattern. 

Si  matches  es  dado,  entonces  sera  definido  con  el  resultado  de  la  busqueda.  $matches[0]  contendra  el 
texto  que  empareja  con  el  patron  en  su  totalidad.  $matches[l]  tendra  la  cadena  que  empareje  con  el 
primer  subpatron  que  este  entre  parentesis  y  asf  sucesivamente. 

Devuelve  true  si  se  encontro  en  la  cadena  un  emparejamiento  dado  el  patron  pattern,  false  si  no  se 
produjo  o  hubo  un  error. 


Ejemplo  1.  Obtener  el  numero  de  la  siguiente  pagina  dada  una  cadena 

if  (preg_match ( " /page\s+# ( \d+) /i " ,  "Go  to  page  #9.",  $parts) ) 

print  "Next  page  is  $parts[l]";  //La  siguiente  pagina  es  $parts[l] 

else 

print  "Page  not  found.";  //  Pagina  no  encontrada 


Examinar  tambien  preg_match_all'),  preg_replace'),  y  preg_splitO- 


preg_match_all  (PHP  3>=  3.0.9,  PHP  4  >=  4.0.0) 


Realiza  un  completo  emparejamiento  de  expresiones 


int  preg_match_all  (string  pattern,  string  subject,  array  matches  [,  int 
order] ) 


Busca  en  subject  todos  los  emparejamientos  de  la  expresion  pattern  y  los  pone  en  matches  de  la 
forma  indicada  por  order. 

Despues  de  encontrar  el  primer  emparejamiento,  las  subsiguientes  busquedas  empiezan  desde  el  punto 
del  ultimo  casamiento. 

order  puede  tener  los  siguientes  valores: 
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PREG_PATTERN_ORDER 

Los  resultados  seran  devueltos  de  manera  que  $matches[0]  es  un  array  con  el  patron  de  busqueda 
completo,  $matches[l]  es  una  array  de  las  cadenas  casadas  por  el  primer  subpatron  que  este  entre 
parentesis  y  asf  sucesivamente. 

preg_match_all (" | <[ A>] +>(.*)</[ A>] +> I U" ,  "<b>example:  </b><div  align=left>this  is  a  test 
print  $out [0]  [0]  .  " . $out  [  0 ]  [  1 ]  . " \n" ; 

print  $out [1]  [0]  . $out  [  1 ]  [  1 ]  .  " \n" 


Esta  ejemplo  dara  como  resultado: 

<b>example:  </b>,  <div  align=lef t>this  is  a  test</div> 
example:  ,  this  is  a  test 


Asf,  $out[0]  contiene  el  array  con  las  cadena  que  casan  completamente  con  el  patron  y  $out[l]  con 
las  cadenas  que  se  encuentran  entre  los  tags. 

PREG_SET_ORDER 

Los  resultados  son  dados  de  manera  que  $matches[0]  es  una  array  del  primer  conjunto  de 
emparejamientos,  $matches[l]  es  un  array  de  los  segundos  conjuntos  de  casamientos  y  asf 
sucesivamente. 

preg_match_all (" | <[ A>] +>(.*)</[ A>] +> | U"  ,  "<b>example:  </b><div  align=left>this  is  a  test 
print  $out [0]  [0]  .  . $out  [ 0]  [  1 ]  . " \n" ; 

print  $out [1] [0] .",  " . $out [ 1 ] [ 1 ] . " \n" 


Este  ejemplo  dara  como  resultado: 

<b>example:  </b>,  example: 

<div  align=left>this  is  a  test</div>,  this  is  a  test 


En  este  caso,  $matches[0]  es  el  primer  conjunto  de  emparejamientos  y  $matches[0][0]  tiene  el 
casamiento  completo,  $matches[0][l]  el  del  primer  subpatron  y  asf  sucesivamente.  Similarmente, 
$matches[l]  es  el  segundo  conjunto  de  emparejamientos,  etc. 


Si  order  no  es  dado,  se  asume  PREG_PATTERN_ORDER. 

Devuelve  el  numero  de  casamientos  completos,  false  si  no  hubo  o  se  produjo  error. 


Ejemplo  1.  Obtener  los  numero  de  telefonos  de  un  texto. 

preg_match_all("/\(?  (\d{3 } ) ?  \) ?  (?  (1)  [\-\s]  )  \d{ 3 } -\d{ 4 } /x" , 

"Call  555-1212  or  1-800-555-1212",  Sphones) ; 
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Examina  tambien  preg_match' ),  prcg_replace')  y  preg_split '). 


preg_replace  (PHP  3>=  3.0.9,  PHP  4  >=  4.0.0) 

Lleva  a  cabo  la  busqueda  de  una  expresion  y  su  sustitucion 

mixed  preg_replace  (mixed  pattern,  mixed  replacement ,  mixed  subject) 


Busca  en  subject  los  emparejamientos  con  pattern  y  los  sustituye  por  replacement. 

replacement  puede  contener  referencias  de  la  forma  \\n.  Estas  seran  sustituidas  por  el  texto 
obtenido  por  el  patron  del  parentesis  nesimo.  n  puede  tener  un  valor  de  cero  a  noventa  y  nueve,  y  \  \  0  se 
refiere  al  texto  casado  por  el  patron  completo.  Para  obtener  el  numero  del  subpatron  de  busqueda,  los 
parentesis  abiertos  son  contados  de  izquierda  derecha  tomando  el  primero  como  uno. 

Si  el  patron  no  es  encontrado  en  subject,  entonces  no  se  realizaran  cambios. 

Todos  los  parametros  de  la  funcion  preg_replace()  pueden  ser  un  array. 

Si  subject  es  un  array,  entonces  la  busqueda  y  sustitucion  es  realizada  para  todos  los  elementos  de 
subject,  y  el  valor  devuelto  es  tambien  un  array. 

Si  pattern  y  replacement  son  arrays,  entonces  preg_replace()  toma  un  valor  desde  cada  array  y 
los  usas  para  buscar  y  sustituir  sobre  subject.  Si  replacement  tiene  menos  valores  que  pattern, 
entonces  la  cadena  vacfa  es  usada  como  valor  para  el  resto  de  sustituciones.  Si  pattern  es  una  array  y 
replacement  es  una  cadena,  entonces  esta  cadena  de  sustitucion  es  usada  para  todos  los  valores  de 
pattern.  Sin  embargo,  lo  contrario  no  tiene  sentido. 

El  modificador  /e  hace  que  la  funcion  preg_replace()  trate  el  parametro  replacement  como  codigo 
PHP  despues  de  que  la  apropiada  sustitucion  sea  hecha.  Atencion,  asegurate  que  replacement  es  un 
codigo  PHP  correcto,  de  otro  modo  PHP  dara  un  error  de  parse  en  la  lrnea  que  contenga  preg_replace(). 

Nota:  Este  modificador  fue  anadido  en  PHP  4.0. 


Ejemplo  1.  Sustituir  varios  valores 

$patterns  =  array  ("/ (19 | 20\d{2 } ) - (\d{ 1, 2 } ) - (\d{ 1, 2 } ) / " ,  " / A\s* {  ( \w+)  } \s*  =  / " ) ; 
$replace  =  array ( "\\3/\\4/\\l" ,  "$\\1  ="); 

print  preg_replace ( $patterns,  $replace,  "{startDate}  =  1999-5-27"); 

Esta  ejemplo  dara  como  resultado: 

$startDate  =  5/27/1999 
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Ejemplo  2.  Usar  el  modificador  /e 

preg_replace ("/ (<\ /? ) (\w+)  <[A>]*>)/e",  " ' \\1 ' . strtoupper ( ' \\2 ' ) . ' \\3'  "  ,  $html_body ) 

Pondra  en  mayuscula  todos  los  tags  HTML  del  texto  de  entrada. 


Examina  tambien  prcg_match '),  preg_match_alL),  y  preg  split'j. 


preg_split 


(PHP  3>=  3.0.9,  PHP  4  >=  4.0.0) 


Divide  una  cadena  dada  una  expresion 


array  preg_split  (string  pattern,  string  subject  [,  int  limit  [,  int  flags]]) 


Nota:  El  parametro  flags  fue  anadido  en  la  Beta  3  de  PHP 

Devuelve  un  array  conteniendo  las  subcadenas  de  subject  divididas  mediante  los  emparejamientos 
limitados  por pattern. 

Si  limit  es  proporcionado,  entonces  solo  limit  subcadenas  son  devueltas. 

Si  el  flags  es  PREG_SPLIT_NO_EMPTY  entonces  las  cadenas  vacias  no  seran  devueltas  por 

preg_split(). 

Ejemplo  1.  Obtener  las  partes  de  una  cadena  de  busqueda 

$keywords  =  preg_split ( " / [ \s, ] +/" ,  "hypertext  language,  programming"); 

Examinar  tambien  preg_match  ),  preg_match_all  [),  y  preg_replaceO- 


preg_quote  (PHP  3>=  3.0.9,  PHP  4  >=  4.0.0) 

Prepara  los  caracteres  de  expresiones 

string  preg_quote  (string  str) 
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preg_quote()  toma  str  y  pone  una  barra  invertida  (\)  delante  de  todo  caracter  que  sea  parte  de  la 
sintaxis  de  las  expresiones.  Es  util  si  tienes  una  cadena  en  tiempo  de  ejecucion  y  puede  contener 
caracteres  especiales. 

Los  caracteres  especiales  de  las  expresiones  son: 

■  \\  +  *  ?  [  A  ]$(){}=!<>  I  : 

Nota:  Esta  funcion  fue  anadida  en  PHP  3.0.9. 


preg_grep(PHP4>=4oo) 

Devuelve  un  array  con  los  elementos  que  casen  con  el  patron 

array  preg_grep  (string  pattern,  array  input) 

preg_grep()  devuelve  un  array  conteniendo  los  elementos  del  array  input  que  emparejen  con  el  patron 
(pattern)  dado. 

Ejemplo  1.  Ejemplo  de  la  funcion  preg_grep() 

preg_grep ( " /A ( \d+) ?\ . \d+$/ " ,  $array) ;  //  encuentra  todos  los  numeros  reales  en  el  array 

Nota:  Esta  funcion  fue  anadida  en  PHP  4.0. 


Modificadores  de  Patrones  (unknown) 


describe  los  modificadores  posibles  en  los  patrones  de  expresiones  regulares  (regex) 

Los  posibles  modificadores  PRCE  (Lunciones  de  Expresiones  Compatibles  con  Perl),  en  este  momento, 
son  mostrados  a  continuation.  Los  nombres  entre  parentesis  se  refieren  a  nombres  internos  PCRE  para 
dichos  modificadores. 
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i  (PCRE_CASELESS) 

Si  es  usado,  no  se  distinguira  entre  mayusculas  y  minusculas. 
m  (PCRE_MULTILINE ) 

Por  defecto,  PCRE  trata  la  cadena  de  entrada  como  si  fuera  una  sola  llnea  de  caracteres  (aun  cuando 
tenga  varias).  El  caracter  especial  de  "inicio  de  linea"  (A)  empareja  solo  al  principio  de  la  cadena, 
mientras  el  caracter  especial  de  "fin  de  llnea"  ($)  casa  solo  el  fin  de  la  entrada,  o  antes  un  caracter  de 
nueva  llnea  (a  menos  que  el  modificador  E  sea  definido).  Esto  es  lo  mismo  que  en  Perl. 

Cuando  este  modificador  es  utilizado,  los  constructores  de  "inicio  de  llnea"  y  "fin  de  llnea"  son 
emparejados  con  el  caracter  de  nueva  llnea.  Esto  es  equivalente  al  modificador  /m  del  Perl.  Si  no  hay 
caracteres  "\n"  en  la  cadena  de  entrada,  o  no  existen  A  o  $  en  el  patron,  entonces  este  modificador  no 
alterara  el  resultado. 


v  (PCRE_DOTALL) 

Si  se  usa,  el  caracter  especial  de  un  punto  en  el  patron  emparejara  todos  los  caracteres,  incluyendo  el  de 
nueva  llnea.  Sin  el,  el  caracter  de  nueva  llnea  es  excluido.  Este  modificador  equivale  a  Is  en  Perl.  Una 
clausula  como  [Aa]  siempre  casa  con  un  caracter  de  nueva  llnea,  independientemente  de  la  utilizacion  de 
este  modificador. 

x  (PCRE_EXTENDED) 

Si  es  definido,  los  caracteres  de  informacion  con  espacios  en  bianco  en  el  patron  son  ignorados  excepto 
cuando  son  precedidos  por  una  barra  invertida  o  dentro  de  una  clase  caracter,  y  los  caracteres  entre  un  # 
fuera  de  una  clase  caracter  y  los  siguientes  caracteres  de  nueva  llnea,  incluidos,  son  ignorados  tambien. 
Esto  es  equivalente  al  /x  en  Perl  y  hace  posible  incluir  comentarios  denbo  de  patrones  complejos.  Sin 
embargo,  esto  es  solo  aplicable  a  caracteres  de  informacion.  Los  caracteres  de  espacio  en  bianco  nunca 
pueden  aparecer  en  la  secuencia  de  caracteres  especiales  de  un  patron,  por  ejemplo  en  la  secuencia  (?( la 
cual  introduce  un  subpatron  condicional. 


Si  es  usado,  preg_replace ')  hace  las  sustituciones  \\  de  forma  habitual,  evalua  el  codigo  PHP  y  usa  el 
resultado  para  realizar  una  sustitucion  en  la  cadena  de  busqueda. 

Solo  preg_replace ')  hace  uso  de  este  modificador  y  es  ignorado  por  las  otras  funciones  PCRE. 

Nota:  Este  modificador  fue  anadido  en  PHP  4.0. 


A  (PCRE_ANCHORED) 

Si  es  definido,  el  patron  es  forzado  a  ser  "anclado",  esto  es,  es  obligado  a  emparejar  solo  desde  el  inicio 
de  la  cadena  (el  "subject  string").  Esta  caracterlstica  tambien  puede  reabzarse  con  el  apropiado  patron,  y 
esta  es  la  unica  manera  de  hacerlo  en  Perl. 

E  (PCRE_DOLLAR_ENDONLY) 

Si  es  usado,  el  caracter  del  dolar  en  el  patron  casara  solo  con  fin  de  la  cadena  de  entrada  (subject). Sin 
este  modificador,  un  dolar  es  tambien  emparejado  con  el  caracter  inmediatamente  antes  del  de  una  nueva 
llnea  (pero  no  antes  de  cualquier  otra  nueva  llnea).  Este  modificador  es  ignorado  si  m  es  definido.  No  hay 
equivalente  en  Perl  para  este  modificador. 
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S 

Cuando  un  patron  va  a  ser  usado  varias  veces,  es  mejor  dedicar  mas  tiempo  a  analizarlo  para  acelerar  el 
proceso  de  casamientos.  Si  es  definido  entonces  se  realizar  un  analisis  adicional.  Estudiar  a  un  patron  es 
solo  util  para  los  no  anclados,  esto  es,  no  tienen  un  caracter  de  inicio  fijado. 

U  (PCRE_UNGREEDY) 

Este  modificador  invierte  la  "codicia"  de  los  cuantificadores  aunque  no  son  ansiosos  por  defecto,  se 
vuelven  codiciosos  si  son  seguidos  por  un  "?".  No  es  compatible  con  Perl,  tambien  puede  usarse  dentro 
del  patron. 

X  (PCRE_EXTRA) 

Este  modificador  activa  caracteristicas  adicionales  del  PCRE  que  no  son  compatible  con  Perl.  Cualquier 
barra  invertida  en  el  patron  que  sea  seguida  por  una  letra  que  no  tenga  una  interpretation  especial 
provocara  un  error,  estas  combinaciones  estan  reservado  para  futuras  ampliaciones.  Por  defecto,  como  en 
Perl,  una  barra  invertida  seguida  por  una  letra  sin  un  significado  especial  es  tratada  literalmente.  No  hay 
otras  caracteristicas  controladas  por  este  modificador  a  la  fecha  de  hoy. 


Sintaxis  de  los  Patrones  (unknown) 

describe  la  sintaxis  de  PCRE  regex 


La  librerfa  PCRE  es  un  conjunto  de  funciones  que  implementan  emparejamientos 
dados  patrones  de  expresiones  regulares  usando  la  misma  sintaxis  y  semantica  que 
Perl  5,  con  unas  pocas  diferencias  (ver  mas  adelante).  La  actual  version 
corresponde  a  Perl  5.005. 


Las  diferencias  descritas  aquf  son  con  respecto  a  Perl  5.005. 

1.  Por  defecto,  un  caracter  de  espacio  en  bianco  es  cualquier  caracter 
que  la  funcion  isspace()  de  la  librerfa  C  reconozca,  asf  es  posible 
compilar  PCRE  con  tablas  alternativas  de  tipos  de  caracteres.  Normalmente 
isspace()  casa  con  el  espacio,  salto  de  pagina,  nueva  lfnea,  retorno  de  carro, 
tabulador  horizontal  y  vertical.  Perl  5  ya  no  incluye  el  tabulador  vertical 

en  su  conjunto  de  caracteres  de  espacio  en  bianco.  La  secuencia  de 
escape  \n  que  estuvo  durante  mucho  tiempo  en  la  documentation  de  Perl  nunca 
fue  reconocida.  Sin  embargo,  el  caracter  fue  tratado  como  espacio  en  bianco 
hasta  la  5.002.  En  5.004  y  5.005  no  casa  \s. 

2.  PCRE  no  permite  repetir  cuantificadores  sobre  sentencias  hacia  adelante. 

Perl  las  permite,  pero  no  de  la  forma  que  puedas  pensar. 

Por  ejemplo,  (?!a){ 3 }  no  dice  que  los  proximos  tres  caracteres  no  son  "a". 

En  realidad  significa  que  los  siguientes  caracteres  no  son  "a"  tres  veces. 
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3.  Los  subpatrones  encontrados  dentro  de  sentencias  de  mas  adelante 
negativas  son  contados,  pero  sus  entradas  en  el  vector  de  desplazamientos 
no  son  definidas.  Perl  define  sus  variables  numericas  desde  cualquiera  de 
tales  patrones  que  son  casados  antes  de  que  la  sentencia  falle  emparejar 
algo,  pero  solo  si  las  sentencies  de  mas  adelante  negativas  contienen  una 
opcion  sola. 

4.  Aunque  los  caracteres  de  cero  binario  son  soportados  en  la  cadena  de 
entrada,  no  son  permitidos  en  un  patron  porque  son  pasados  como  un  cadena 
tfpica  de  C,  terminada  por  cero.  La  secuencia  de  escape  "\0"  puede  ser 
usada  en  el  patron  para  representar  el  cero  binario. 

5.  Las  siguientes  secuencias  de  Perl  no  son  soportadas: 

\1,  \u,  \L,  \U,  YE,  \Q.  En  efecto,  estas  son  implementadas  por 
manipuladores  de  cadenas  tfpicos  de  Perl  y  no  son  parte  de  los  patrones  del 
motor  de  busqueda. 

6.  La  secuencia  \G  de  Perl  no  es  soportada  ya  que  no  es  relevante  para 
emparejamientos  de  patrones  sencillos. 

7.  Obviamente,  PCRE  no  soporta  el  constructor  (?{code}) 

8.  Hay  algunas  diferencias  en  Perl  5.005_02  respecto  a  las  definiciones 
de  las  cadenas  de  captura  cuando  parte  de  un  patron  es  repetido.  Por 
ejemplo,  casando  "aba"  con  el  patron  /A(a(b)?)+$/  define  $2  al  valor  "b", 
pero  emparejando  "aabbaa"  con  /A(aa(bb)?)+$/  deja  $2  sin  definir.  Sin 
embargo,  si  el  patron  es  cambiado  a  /A(aa(b(b))?)+$/  entones  $2  (y  $3)  son 
definidos. 

En  Perl  5.004  $2  es  definido  en  ambos  casos,  y  tambien  es  cierto  en  PCRE. 

Si  en  el  futuro  Perl  cambia  a  una  regia  diferente,  PCRE  puede  cambiar  para 
seguirla. 

9.  Otra  discrepancia  aun  no  resuelta  es  que  en  Perl  5.005_02  el  patron 
/A(a)?(?(l)alb)+$/  casa  la  cadena  "a",  pero  en  PCRE  eso  no  es  asf.  Sin 
embargo,  en  ambos  Perl  y  PCRE  /A(a)?a/  empareja  "a"  dejando  $1  sin  definir. 

10.  PCRE  da  algunas  extensiones  para  facilitar  las  expresiones  de  PERL: 

(a)  Aunque  las  sentencias  de  mas  adelante  deben  emparejar  cadenas  de  longitud  fija, 
cada  opcion  de  una  sentencia  de  punto  actual  puede  casar  con  una  cadena  de 
longitud  diferente.  Perl  5.005  requiere  que  todas  ellas  tengan  la  misma 

longitud. 

(b)  Si  es  definido  PCRE_DOLLAR_ENDONLY  y  PCRE_MULTILINE  no  lo  es,  el 
caracter  especial  $  solo  casa  con  el  final  de  la  cadena. 
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(c)  Si  se  define  PCRE_EXTRA,  una  barra  invertida  seguida  de  una  letra  sin 
un  significado  especial  provoca  un  error. 

(d)  Si  defines  PCRE_UNGREEDY,  la  voracidad  de  los  cuantificadores  de 
repetition  es  invertida,  esto  es,  por  defecto  son  no  codiciosos,  pero 
seguidos  por  una  interrogation  si  lo  son. 


La  sintaxis  y  la  semantica  de  las  expresiones  soportadas  por  PCRE  es 
descrita  a  continuation.  Las  expresiones  son  descritas  en  la  documentacion 
del  Perl  y  en  numerosos  libros,  algunos  de  los  cuales  tienen  mucho 
ejemplares,  Jeffrey  Friedl’s  "Mastering  Regular  Expressions",  publicado 
por  O’Reilly  (ISBN  1-56592-257-3),  las  cubre  con  gran  detalle.  La  presente 
description  es  propuesta  como  documentacion  de  referencia. 

Una  expresion  es  un  patron  que  es  emparejada  repetidamente,  dada  una  cadena 
de  entrada,  de  izquierda  a  derecha.  Muchos  caracteres  se  representan  a  ellos 
mismos  en  el  patron.  Como  un  ejemplo  trivial,  el  patron 

The  quick  brown  fox 

casa  una  parte  de  una  cadena  de  entrada  que  es  identica  a  ella.  El  poder 
de  las  expresiones  proviene  de  la  posibilidad  de  incluir  alternativas  y 
repeticiones  en  el  patron.  Estos  son  codificados  en  el  patron  usando 
meta-characters  (caracteres 

especiales  tambien  llamados  meta  caracteres),  los  cuales  no  se  representan 
a  ellos  mismos,  en  vez  de  eso,  son  interpretados  de  una  manera  especial. 

Hay  dos  diferentes  conjuntos  de  caracteres  especiales:  aquellos  que  son 
reconocidos  en  cualquier  parte  en  el  patron  excepto  dentro  corchetes  (’[’  y  ’]’), 
y  aquellos  que  son  reconocidos  dentro.  Fuera  de  los  corchetes,  los  caracteres 
especiales  son: 

\  caracter  de  escape  generico  con  diferentes  usos 

A  secuencia  de  inicio  de  la  cadena  de  entrada  (o  lfnea,  en  modo  multilmea) 

$  secuencia  de  fin  de  la  cadena  de  entrada  (o  lfnea,  en  modo  multilmea) 

empareja  cualquier  caracter  excepto  el  de  nueva  lfnea  (por  defecto) 

[  inicia  definition  de  clase  de  caracteres 

I  inicio  de  option  altemativa 

(  inicio  de  subpatron 

)  tin  de  subpatron 

?  amplia  el  significado  de  ( 

tambien  es  el  cuantificador  0  6  1 
tambien  es  el  cuantificador  minimizado 
*  cero  o  mas  cuantificadores 
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+  uno  o  mas  cuantific  adores 

{  inicia  el  cuantificador  min/max 


Parte  de  un  patron  dentro  de  corchetes  ([])  es  llamado  un  "character  class" 
(clase  de  caracteres).  En  una  clase  de  caracteres  los  unicos  caracteres 
especiales  son: 

\  caracter  de  escape  generico 
A  niega  la  clase,  pero  solo  si  el  primer  caracter 
indica  un  rango  de  caracteres 
]  finaliza  la  clase  de  caracteres 

Las  secciones  siguientes  describen  el  uso  de  cada  uno  de  los  caracteres 
especiales  (meta  caracteres). 

BARRA  INVERTIDA 

El  caracter  de  barra  invertida  tiene  varios  usos.  Primero,  si  es  seguido 
por  un  caracter  que  no  sea  alfanumerico,  toma  el  significado  que  el 
caracter  pueda  tener.  Este  uso  de  la  barra  invertida,  como  un  caracter  de 
escape,  se  aplica  tanto  dentro  como  fuera  de  las  clases  de  caracteres. 

Por  ejemplo,  si  quieres  casar  un  caracter  debes  escribir  "\*"  en  el  patron. 
Esto  es  aplicable  ya  sea  o  no  el  caracter  siguiente  interpretado  como  un 
caracter  especial,  por  eso  siempre  es  aconsejable  preceder  un  caracter 
no  alfanumerico  con  "\"  para  especificar  que  se  representa  a  el  mismo.  En 
particular,  si  quieres  casar  una  barra  invertida,  escribe  "\\". 

Si  el  patron  es  compilado  con  la  option  PCRE_EXTENDED  ,  los  espacios  en 
bianco  en  el  patron  (fuera  de  una  clase  de  caracteres)  y  los  caracteres  entre 
un  "#"  fuera  de  una  clase  de  caracteres  y  el  caracter  de  nueva  lrnea 
son  ignorado.  Una  barra  invertida  de  escape  puede  usarse  para 
incluir  un  espacio  en  bianco  o  el  caracter  "#"  como  parte  del  patron. 

Un  segundo  uso  de  la  barra  invertida  sirve  para  codificar  caracteres  no 
imprimibles  en  los  patrones  de  una  manera  visible.  No  hay  restricciones 
sobre  la  apariencia  de  los  caracteres  no  imprimibles,  quitando  el  cero 
binario  de  termination  de  un  patron,  pero  cuando  un  patron  es  preparado 
con  un  editor  de  texto,  normalmente  es  facil  utilizar  una  de  las  siguientes 
secuencias  de  escape  que  representan  sus  caracteres  binarios: 

\a  alarma,  esto  es,  el  caracter  BEL  (07  en  hexadecimal) 

\cx  "control-x",  donde  x  es  cualquier  caracter 
\e  escape  (IB  en  hexadecimal) 

\f  nueva  pagina  (0C  en  hexadecimal) 

\n  nueva  lrnea  (0A  en  hexadecimal) 

\r  retorno  de  carro  (0D  en  hexadecimal) 
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\t  tabulador  (09  en  hexadecimal) 

Yxhh  caracter  con  codigo  hh  en  hexadecimal 
\ddd  caracter  con  codigo  ddd  en  octal 

El  efecto  de  "\cx"  es  como  sigue:  si  "x"  es  una  letra  minuscula, 
es  convertida  a  mayuscula.  Entonces  el  sexto  bit  del  caracter  (40  en 
hexadecimal)  es  invertido.  Esto  es,  "\cz"  es  1A  en  hexadecimal,  pero  "\c{" 
es  3B  en  hexadecimal,  mientras  "\c;"  es  7B  en  hexadecimal. 

Despues  de  "\x",  hasta  dos  dfgitos  hexadecimales  son  lefdos  (las  letras 
pueden  ser  mayusculas  o  minusculas). 

Despues  de  "\0"  son  lefdos  dos  dfgitos  octales  mas.  En  ambos  casos,  si  hay 
menos  de  dos  dfgitos,  se  usrara  lo  que  haya.  Esto  es,  la  secuencia  "\0\x\07" 
indica  dos  ceros  binarios  seguidos  por  un  caracter  BEL.  Asegurate  dar  dos 
dfgitos  despues  del  inicial  cero  si  el  caracter  que  sigue  es  un  dfgito  octal. 

El  uso  de  una  barra  invertida  seguido  por  otro  dfgito  que  no  sea  el  cero 
es  complejo.  Fuera  de  una  clase  caracter,  PCRE  interpreta  cualquier  dfgito 
como  un  numero  decimal.  Si  el  numero  es  menor  que  diez,  o  si  ha  habido 
al  menos  tantos  parentesis  capturados  a  la  izquierda  en  la  expresion, 
entonces  la  secuencia  entera  es  tomada  como  una  back 
reference  (referenda  atras).  Una  description 

de  como  trabaja  esto  es  dada  despues,  siguiendo  la  discusion  de  subpatrones 
con  parentesis. 

Dentro  de  una  clase  caracter,  o  si  el  numero  decimal  es  mayor  que  nueve  y 
no  ha  habido  tantos  subpatrones  capturados  PCRE  relee  los  tres  dfgitos 
octales  siguientes  a  la  barra  invertida  y  genera  un  byte  desde  los  ocho 
bits  menos  significativos  del  valor.  Cualquier  dfgito  a  continuation  se 
representa  a  el  mismo.  Por  ejemplo: 

\040  es  otro  modo  de  escribir  un  espacio 

\40  es  lo  mismo,  siempre  que  haya  menos  de  cuarenta  subpatrones  abiertos 

\7  siempre  es  una  referenda  atras 

\1 1  puede  ser  una  referenda  atras  o  un  tabulador 

\01 1  siempre  es  un  tabulador 

\01 13  es  el  caracter  con  codigo  octal  113  (ya  que  no  puede  haber  mas  de 
noventa  y  nueve  referencias  atras) 

\377  es  un  byte  con  todos  sus  bits  a  uno 

\8 1  puede  ser  una  referencia  atras  o  un  cero  binario  seguido  por 
dos  caracteres  "8"  y  "1" 

Ten  en  cuenta  que  el  valor  octal  de  un  numero  mayor  o  igual  a  cien  no  debe 
ser  precedido  por  un  cero  ya  que  no  son  lefdos  mas  de  tres  dfgitos  octales. 

Todas  las  secuencias  que  definen  el  valor  de  un  byte  pueden  ser  usadas 
tanto  dentro  como  fuera  de  la  clase  caracter.  Ademas,  la  secuencia 
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"\b"  es  interpretada  como  el  caracter  backspace  (hex  08)  dentro.  Fuera  es 
definido  de  otra  manera  (ver  mas  adelante). 

El  tercer  uso  de  la  barra  invertida  es  para  especificar  los  tipos  de 
caracteres  genericos: 

\d  cualquier  un  dfgito  decimal 

\D  cualquier  caracter  que  no  sea  un  dfgito  decimal 

\s  cualquier  caracter  de  espacio  en  bianco  (whitespace) 

\S  cualquier  caracter  que  no  sea  un  espacio  en  bianco 
\w  cualquier  caracter  de  "palabra" 

\W  cualquier  caracter  que  no  se  de  "palabra" 

Cada  pareja  de  secuencia  de  escape  divide  el  conjunto  global  de  caracteres 
en  dos.  Cualquier  caracter  dado  empareja  en  uno  y  solo  uno  de  cada  pareja. 

Un  caracter  de  "palabra"  es  cualquier  letra  o  dfgito  o  el  caracter  subrayado, 
esto  es,  cualquier  caracter  puede  ser  parte  de  una  "palabra"  en  Perl.  La 
definicion  de  letras  y  dfgitos  es  controlada  por  la  tabla  de  caracteres  de 
PERL,  y  puede  ser  variada  si  las  especificaciones  regionales  son  tomadas  en 
cuenta  (ver  "Soporte  regional  mas  adelante").  Por  ejemplo,  en  Francia  algunos 
caracteres  tienen  un  codigo  superior  a  128,  para  representar  las  letras 
acentuadas,  y  son  emparejados  por  \w. 

Estas  secuencias  de  tipos  de  caracteres  pueden  aparecer  tanto  dentro  como 
fuera  de  las  clases  caracter.  Cada  una  casa  un  caracter  del  tipo  apropiado. 

Si  el  punto  de  casamiento  actual  es  el  final  de  la  cadena,  todo  ello  falla, 
ya  que  no  hay  mas  caracteres  que  casar. 

El  cuarto  uso  de  la  barra  invertida  es  para  ciertas  sentencias  (assertions). 

Una  sentencia  especifica  una  condicion  que  tiene  que  ser  encontrada  en 
un  punto  particular  de  un  emparejamiento,  sin  utilizar  ningun  caracter  de  la 
cadena  de  entrada.  El  uso  de  subpatrones  para  sentencias  mas  complicadas 
es  descrito  despues.  Las  sentencias  de  barra  invertida  son 

\b  limites  de  palabra 
\B  no  sean  limites  de  palabra 

\A  inicio  de  la  cadena  de  entrada  (independiente  del  modo  multilfnea) 

\Z  fin  de  la  cadena  de  entrada  o  de  una  nueva  lfnea  delante  del  final 
(independiente  del  modo  multilfnea) 

\z  fin  de  la  cadena  de  entrada  (independiente  de  modo  multilfnea) 

Estas  sentencias  no  pueden  aparecer  dentro  de  una  clase  caracter  (pero  ten 
en  cuenta  que  "\b"  tiene  un  significado  diferente,  quiere  decir  el  caracter 
backspace  dentro  de  una  clase  caracter) 

Un  lfmite  de  palabra  es  una  posicion  en  la  cadena  de  entrada  donde  un 
caracter  y  el  anterior  no  emparejan  con  \w  o  \W  (por  ejemplo,  uno  casa  con 
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\w  y  el  otro  con  \W),  o  el  principio  o  el  final  de  la  cadena  si  el  primero 
o  el  ultimo  caracter  emparejan  con  \w,  respectivamente. 

Las  sentencias  \A,  \Z  y  \z  se  diferencian  de  los  tradicionales  circunflejo 

y  dolar  (ver  mas  adelante)  en  que  solo  emparejan  el  inicio  y  fin  de  la 

cadena  de  entrada  sin  tener  en  cuenta  las  opciones  definidas.  No  les  afectan 

las  opciones  PCRE_NOTBOL  o  PCRE_NOTEOL.  La  diferencia  entre  XL  y  \z  es  que 

XL  casa  antes  una  nueva  lfnea  que  es  el  ultimo  caracter  de  la  cadena  como 

tambien  el  final  de  la  cadena,  sin  embargo  \z  solo  casa  el  final. 

CIRCUNFLEJO  Y  DOLAR 

Fuera  de  una  clase  caracter,  en  el  modo  de  emparejamiento  por  defecto,  el 
caracter  circunflejo  es  una  sentencia  la  cual  es  verdadera  solo  si  el  punto 
de  casamiento  actual  es  el  inicio  de  la  cadena  de  entrada.  Dentro  de  una 
clase  caracter,  el  circunflejo  tiene  significado  completamente  distinto 
(ver  mas  adelante). 

El  circunflejo  no  necesita  ser  el  primer  caracter  del  patron  si  son  posibles 
un  numero  de  alternativas,  pero  sera  la  primera  cosa  en  cada  alternativa 
en  la  cual  aparezca  si  el  patron  casa  esa  opcion. 

Si  todas  las  alternativas  posibles  empiezan  con  un  circunflejo,  esto  es, 
si  el  patron  es  obligado  a  casar  solo  con  en  el  inicio  de  la  cadena  de  entrada, 
se  dice  que  es  un  patron  "anclado".  Tambien  hay  otros  constructores  que 
pueden  hacer  que  un  patron  sea  anclado. 

Un  caracter  de  dolar  es  una  sentencia  que  es  verdadera  solo  si  el 
punto  de  emparejamiento  actual  es  el  final  de  la  cadena  de  entrada,  o 
inmediatamente  antes  de  un  caracter  de  nueva  lfnea,  el  cual  es  el  ultimo 
caracter  en  la  cadena,  por  defecto.  El  dolar  no  necesita  ser  el  ultimo 
caracter  del  patron  si  hay  varias  alternativas,  pero  sera  el  ultimo  elemento 
en  cualquier  alternativa  en  el  que  aparezca.  El  dolar  no  tiene 
un  significado  especial  en  una  clase  caracter. 

El  significado  del  dolar  puede  ser  cambiado  para  que  solo  empareje  el 

final  de  la  cadena  de  entrada  definiendo  la  opcion  PCRE_DOLLAR_ENDONLY  a  la 

hora  de  compilar  o  tiempo  de  ejecucion.  Esto  no  afecta  a  la  sentencia  XL. 

El  significado  de  los  caracteres  circunflejo  y  dolar  cambia  si  la  opcion 

PCRE_MULTILINE  es  definida.  Cuando  este  es  el  caso,  casan,  respectivamente, 

inmediatamente  antes  y  despues  de  un  caracter  "\n"  interno, 

ademas  de  emparejar  con  el  inicio  y  el  final  de  la  cadena.  Por  ejemplo,  el 

patron  /Aabc$/  casa  con  la  cadena  de  entrada  "def\nabc"  en  modo  multilfnea, 

pero  en  otro  modo  no.  Consecuentemente,  los  patrones  anclados  son  en  modo 

lfnea  ya  que  todas  las  opciones  que  empiezan  con  "A"  no  son  ancladas  en  modo 

multilfnea.  La  opcion  PCRE_DOLLAR_ENDONLY  es  ignorada  si  PCRE_MULTILINE 

definido. 
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Ten  en  cuenta  que  las  secuencias  \A,  \Zy\z  pueden  ser  usadas  para  casar 
el  inicio  y  el  final  de  la  cadena  en  ambos  modos,  y  si  todas  las  opciones 
de  un  patron  empiezan  con  \A  siempre  es  anclado,  independientemente  de  si 
PCRE_MULTILINE  es  definido  o  no. 

FINAL  (PUNTO) 

Fuera  de  una  clase  caracter,  un  punto  en  el  patron  casa  con  un  caracter 
cualquiera  en  la  cadena  de  entrada,  incluyendo  un  caracter  no  imprimible, 
exceptuando  el  de  nueva  lfnea  (por  defecto).  Si  la  opcion  PCRE_DOTALL  es 
definida,  entonces  los  puntos  casan  con  los  de  nueva  li'nea  tambien.  El 
manejo  de  puntos  es  completamente  independiente  del  uso  del  circunflejo  y  el 
dolar,  la  unica  relation  entre  ellos  son  los  caracteres  de  nueva  li'nea.  Los 
puntos  no  tienen  un  significado  especial  dentro  de  una  clase  caracter. 

CORCHETES 

Un  corchete  de  apertura  crea  una  clase  caracter,  terminada  por  uno  de  cierre. 

Un  corchete  de  cierre  no  tiene  un  significado  especial.  Si  un  corchete  de 
cierre  es  necesitado  como  un  miembro  de  la  clase,  sera  el  primer  caracter 
de  datos  en  la  clase  (despues  de  un  circunflejo  inicial,  si  esta  presente) 
o  con  una  barra  invertida  antes. 

Si  una  clase  caracter  casa  con  un  caracter  unico  en  la  cadena;  el  caracter 
debe  estar  en  el  conjunto  de  los  caracteres  definidos  por  la  clase,  a  menos 
que  el  primero  sea  un  circunflejo,  en  cuyo  caso  el  caracter  de  la  cadena  de 
entrada  no  debe  estar  en  el  conjunto  definido  por  la  clase.  Si  un  circunflejo 
es  necesitado  como  un  miembro  de  la  clase,  asegurate  que  no  es  el  primero  o 
es  precedido  por  una  barra  invertida. 

Por  ejemplo,  la  clase  caracter  [aeiou]  empareja  cualquier  vocal  minuscula, 
mientras  [Aaeiou]  casa  cualquier  caracter  que  no  sea  una  vocal  minuscula. 

Ten  en  cuenta  que  un  circunflejo  es  una  notation  convenida  para  especificar 
los  caracteres  que  estan  en  la  clase  enumerando  los  que  no  lo  estan.  No  es 
una  sentencia:  consume  un  caracter  de  la  cadena  de  entrada  y  falla  si 
el  punto  actual  es  final. 

Cuando  se  define  el  emparejamiento  sin  tener  en  cuenta  mayusculas  y  minusculas 
(caseless),  cualquier  letra  en  una  clase  representa  ambas,  por  ejemplo, 
un  patron  caseless  [aeiou]  empareja  tanto  "A"  como  "a"  y  un  caseless 
[Aaeiou]  no  casa  con  "A" 

El  caracter  de  nueva  lfnea  nunca  es  tratado  de  un  modo  especial  en  una 
clase  caracter,  aunque  se  hallan  definido  cualquiera  de  las  opciones 
PCRE_DOTALL  o  PCRE_MULTILINE.  Una  clase  como  [Aa]  siempre  casa  con  una 
nueva  lfnea. 

El  caracter  de  menos  puede  ser  usado  para  especificar  un  rango  de  caracteres 
en  una  clase  miembro.  Por  ejemplo,  [d-m]  casa  con  cualquier  letra  entre  d 
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y  m  ambas  incluidas.  Si  un  caracter  de  menos  es  necesitado  en  una  clase, 
debe  ser  precedido  por  una  barra  invertida  o  aparecer  en  una  posicion  donde 
no  pueda  ser  interpretado  como  indicador  de  una  rango,  normalmente  al  inicio 
o  al  final  de  la  clase. 

No  es  posible  tener  el  caracter  literal "]"  como  el  de  final  de  un  rango. 

Un  patron  como  [W-]46]  es  interpretado  como  una  clase  de  dos  caracteres 
("W"  y  seguido  por  la  cadena  literal  "46]",  por  lo  que  emparejana  con 
"W46]"  o  "-46]".  Sin  embargo,  si  el  caracter  "]"  es  precedido  con  una  barra 
invertida  es  tornado  por  el  final  del  rango,  asf  [W-\]46]  es  interpretado 
como  una  clase  conteniendo  un  rango  seguido  por  dos  caracteres.  La 
representacion  octal  o  hexadecimal  de  "]"  puede  ser  usada  para  finalizar 
un  rango. 

Los  rangos  trabajan  en  la  secuencia  ASCII.  Se  pueden  especificar  mediante 
la  representacion  numerica  de  los  mismos,  por  ejemplo  [\000-\037].  Si 
un  rango  que  incluye  letras  es  usado  cuando  es  definida  la  opcion  de  no 
tener  en  cuenta  mayusculas  y  minusculas  casan  ambas.  Por  ejemplo,  [W-c] 
es  equivalente  a  [][\A_‘wxyzabc],  teniendo  en  cuenta  mayusculas  y 
minusculas,  y  si  la  tabla  de  caracteres  para  la  region  "fr"  es  usada, 
entonces  [\xc8-\xcb]  empareja  los  caracteres  E  acentuados  en  ambos  casos. 

Los  tipos  de  caracteres  \d,  \D,  \s,  \S,  \w,  y  \W  tambien  pueden  aparecer 
en  una  clase  caracter  y  anaden  los  caracteres  que  ellos  casen  para  la  clase. 

Por  ejemplo,  [\dABCDEF]  casa  cualquier  dfgito  hexadecimal.  Un  circunflejo 
puede  ser  usado  convenientemente  con  el  tipo  de  caracter  mayusculo  para 
especificar  un  conjunto  mas  restrictivo  de  caracteres  que  el  de  un  casamiento 
con  tipo  de  caracter  minusculo.  Por  ejemplo,  la  clase  [A\W_]  empareja 
cualquier  letra  o  digito  pero  no  el  subrayado. 

Todos  los  caracteres  no  alfanumericos  y  los  diferentes  a  \,  -,  A  (al 
principio)  y  ]  no  tienen  un  significado  especial  en  una  clase,  y  estos 
tampoco  si  son  definidos  convenientemente. 

BARRA  VERTICAL 

Los  caracteres  de  barra  vertical  son  usados  para  separar  patrones 
alternativos.  Por  ejemplo,  el  patron 

gilbertlsullivan 

casa  con  "gilbert"  o  "sullivan".  Cualquier  cantidad  de  opciones  pueden  ser 
implementadas,  y  una  alternativa  vacfa  se  permite  (emparejando  la 
cadena  vacfa).  El  proceso  de  casamiento  intenta  cada  una  de  izquierda  a 
derecha,  y  la  primera  que  valga  es  usada.  Si  las  alternativas  estan  dentro 
de  un  subpatron,  "valga"  significa  que  casa  el  resto  del  patron  principal 
como  tambien  la  alternativa  en  el  subpatron. 
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DEFINIENDO  LAS  OPCIONES  INTERNAS 

Las  definiciones  de  PCRE_CASELESS,  PCRE_MULTILINE,  PCRE_DOTALL, 
y  PCRE_EXTENDED  pueden  ser  cambiadas  desde  dentro  del  patron  mediante 
una  secuencia  de  letras  de  opciones  de  Perl  encerradas  entre  "(?"  y 
Las  letras  de  opciones  son 

i  para  PCRE_CASELESS 
m  para  PCRE_MULTILINE 
s  para  PCRE_DOTALL 
x  para  PCRE_EXTENDED 

Por  ejemplo,  (?im)  define  sin  tener  en  cuenta  mayusculas  y  minusculas  y  modo 
multilmea.  Tambien  es  posible  eliminar  estas  opciones  precediendo  las 
letras  con  un  menos  y  una  combinacion  de  definiciones  y  eliminaciones  tal 
como  (?im-sx),  la  cual  define  PCRE_CASELESS  y  PCRE_MULTILINE  mientras 
elimina  PCRE_DOTALL  y  PCRE_EXTENDED,  tambien  se  permite.  Si  una  letra 
aparece  antes  y  despues  del  menos,  la  opcion  es  eliminada. 

El  ambito  de  estas  opciones  cambia  dependiendo  donde  ocurra  la  definicion. 

Las  definiciones  que  son  hechas  fuera  de  subpatrones  (como  antes),  el  efecto  es 
el  mismo  que  si  la  opcion  se  define  o  elimina  al  inicio  del  casamiento.  Los 
siguientes  patrones  se  comportan  todos  de  la  misma  manera: 

(?i)abc 

a(?i)bc 

ab(?i)c 

abc(?i) 

el  cual  tiene  el  mismo  efecto  que  compilar  el  patron  abc  con  la  opcion 
PCRE_CASELESS.  En  otras  palabras,  tales  definiciones  de  "nivel  superior" 
se  aplican  a  todo  el  patron  (a  menos  que  haya  otro  cambio  dentro  del 
subpatron).  Si  hay  mas  de  una  definicion  de  la  misma  opcion  en  el  mismo 
nivel  superior,  la  definicion  mas  a  la  derecha  se  usa. 

Si  un  cambio  de  opcion  sucede  dentro  de  un  subpatron,  el  efecto  es  diferente. 

Esto  es  un  cambio  respecto  de  la  conducta  de  Perl  5.005.  Un  cambio  de  opcion 
dentro  de  un  subpatron  afecta  solo  a  la  parte  del  subpatron  que  lo  sigue, 
por  eso 

(a(?i)b)c 

empareja  abc  y  aBc  y  ninguna  otra  cadena  (asumiendo  que  no  es  usado 
PCRE_CASELESS).  De  este  modo,  las  opciones  pueden  ser  hechas  para 
tener  diferente  significado  en  diferente  partes  del  patron.  Cualquier 
cambio  realizado  en  una  alternativa  provoca  que  todo  el  subpatron  la  use. 

Por  ejemplo. 
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(a(?i)blc) 

empareja  "ab",  "aB",  "c",  y  "C",  siempre  y  cuando  case  "C"  la  primera 
opcion  es  abandonada  antes  de  definir  la  opcion.  Esto  es  porque  los  efectos 
de  definiciones  de  opcion  ocurren  en  tiempo  de  compilation.  De  otro  modo, 
estos  serfa  una  conducta  muy  rara. 

Las  opciones  especfficas  PCRE  PCRE_UNGREEDY  y  PCRE_EXTRA  pueden  ser 
cambiadas  del  mismo  modo  que  las  opciones  compatibles  con  Perl  usando 
los  caracteres  U  y  X  respectivamente.  La  bandera  (?X)  es  especial  ya  que 
siempre  debe  aparecer  antes  que  cualquier  otra  en  el  patron,  incluso  cuando 
es  definida  a  nivel  superior.  Es  mejor  ponerla  en  el  inicio. 

SUBPATRONES 

Los  subpatrones  son  delimitados  por  parentesis  y  pueden  estar  anidados. 

Marcando  parte  de  un  patron  como  un  subpatron  permite  dos  cosas: 

1.  Define  un  conjunto  de  opciones.  Por  ejemplo,  el  patron 
cat(aractlerpillarl) 

empareja  con  "cat",  "cataract",  or  "caterpillar".  Sin  los  parentesis, 
casarfa  "cataract",  "erpillar"  o  la  cadena  vacfa. 

2.  Define  el  subpatron  como  un  subpatron  capturado.  Cuando  el  patron  sea 
emparejado  por  completo,  esa  portion  de  la  cadena  de  entrada  que  casa  con 
el  subpatron  es  devuelta  mediante  el  argumento  ovector 

de  pcre_exec().  Los  parentesis  abiertos  son  contados  de 

izquierda  a  derecha  (empezando  por  uno)  para  definir  los  numeros  de 

subpatrones  capturados. 

Por  ejemplo,  si  la  cadena  "the  red  king"  es  casada  con  el  patron 
the  ((redlwhite)  (kinglqueen)) 

las  subcadenas  capturadas  son  "red  king",  "red",  y  "king"  y  los  numeros 
son  1,2  y  3 

El  hecho  de  que  los  parentesis  realicen  dos  funciones  no  siempre  es  util. 

A  menudo,  hay  veces  que  un  subpatron  agrupado  es  necesitado  sin  una 
querer  una  captura.  Si  un  parentesis  abierto  le  sigue  el 
subpatron  no  hace  ninguna  captura,  y  no  es  contado  cuando  compute  el 
numero  de  subpatrones  capturados.  Por  ejemplo,  si  la  cadena  "the  white 
queen"  es  casada  con  el  patron 

the  ((?:redlwhite)  (kinglqueen)) 
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las  subcadenas  capturadas  son  "white  queen"  y  "queen"  y  son  numeradas  como 
1  y  2.  El  numero  maximo  de  subcadenas  es  de  99  y  el  numero  maximo  de 
subpatrones,  capturados  o  no,  es  de  200. 

Como  un  atajo,  si  cualquier  definicion  de  opcion  es  necesitada  al  inicio 
de  un  subpatron  no  capturado,  las  letras  de  opciones  pueden  aparecer  entre 
"?"  y  Asf  los  dos  patrones 

(?i:saturdaylsunday) 

(?:(?i)saturdaylsunday) 

emparejan  como  el  mismo  conjunto  de  cadena  de  entrada  exactamente.  Ya  que 
las  alternativas  son  intentadas  de  izquierda  a  derecha,  y  las  opciones 
no  son  dejadas  de  tener  en  cuenta  hasta  que  el  final  de  subpatron  se 
alcanza,  una  definicion  de  opcion  en  una  alternativa  afecta  al  resto,  por 
eso  el  patron  anterior  empareja  tanto  con  "SUNDAY"  como  con  "Saturday". 

REPETICION 

La  repeticion  es  especificada  por  cuantificadores,  la  cual  puede  utilizarla 
cualquiera  de  los  siguientes  elementos: 

un  caracter,  posiblemente  precedido  por  el  meta  caracter  . 
una  clase  caracter 

una  referenda  atras  (ver  la  proxima  seccion) 

un  subpatron  con  parentesis  (a  menos  que  sea  una  sentencia,  ver  mas  adelante) 

El  cuantificador  de  repeticion  general  indica  un  numero  mfnimo  y  un  maximo 
de  casamientos  permitidos,  dando  los  dos  numeros  entre  Haves,  separados 
por  coma.  El  numero  debe  ser  menor  que  65536,  y  el  primero  debe  ser  menor 
o  igual  que  el  segundo.  Por  ejemplo: 

z  { 2,4 } 

casa  con  "zz",  "zzz",  o  "zzzz".  Una  Have  de  cierre  por  si  misma  no  es  un 
caracter  especial.  Si  el  segundo  numero  es  omitido,  pero  aparece  la  coma, 
entonces  no  hay  lfmite  superior;  si  el  segundo  numero  y  la  coma  son 
omitidos,  el  cuantificador  indica  el  numero  exacto  de  repeticiones.  Asf 

[aeiou]{3,} 

empareja  al  menos  tres  vocales  seguidas,  pero  pueden  ser  muchas  mas,  mientras 

\d{8} 

casa  exactamente  ocho  dfgitos.  Una  Have  abierta  en  una  position  donde  un 
cuantificador  no  es  permitido  o  una  que  no  empareje  con  la  sintaxis  de  un 
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cuantificador  es  tomada  como  un  caracter  literal.  Por  ejemplo,  {,6}  no  es 
un  cuantificador,  pero  sf  una  cadena  literal  de  cuatro  caracteres. 

Se  permite  el  cuantificado  {0},  provocando  que  la  expresion  se  comporte 
como  si  el  elemento  anterior  y  el  cuantificador  no  estuvieran  presentes. 

Por  conveniencia  (y  compatibilidad  historica)  los  cuantificadores  mas  comunes 
tienen  abreviaciones  de  un  solo  caracter. 

*  es  equivalente  a  { 0, } 

+  es  equivalente  a  { 1, } 

?  es  equivalente  a  {0,1} 

Es  posible  construir  bucles  infinitos  mediante  un  subpatron  que  pueda 
casar  ningun  caracter  con  un  cuantificador  que  no  tenga  lfmite  superior, 
por  ejemplo: 

(a?)* 

Las  primeras  versiones  de  Perl  y  PCRE  dan  un  error  en  tiempo  de  compilation 
para  tales  patrones.  Sin  embargo,  ya  que  existen  casos  donde  esto  puede  ser 
util,  esto  patrones  son  aceptados  ahora,  pero  si  cualquier  repetition  del 
subpatron  no  casa  ningun  caracter,  el  bucle  es  roto. 

Por  defecto,  los  cuantificadores  son  "codiciosos",  esto  es,  casan  tantas 
veces  como  les  es  posible  (hasta  el  numero  maximo  de  veces  permitido),  sin 
provocar  que  el  resto  del  patron  falle.  El  ejemplo  clasico  de  donde  viene 
este  problema  es  en  intentar  casar  comentarios  en  los  programas  en  C. 

Estos  aparecen  entre  las  secuencias  /*  y  */  y  dentro  de  la  secuencia  los 
caracteres  *  y  /  pueden  aparecer  individualmente.  Un  modo  de  casar 
comentarios  en  C  es  aplicando  el  patron 

para  la  cadena 

/*  first  command  */  not  comment  /*  second  comment  */ 

falla,  porque  casa  la  cadena  entera  debido  a  la  voracidad  del  elemento  .* 

Sin  embargo,  si  un  cuantificador  le  siguw  un  signo  de  interrogation 
entonces  cesa  la  voracidad  y  empareja  el  minimo  numero  de  veces  posibles, 
asf  el  patron 

!\*  *9 

hace  las  cosas  correctamente  con  los  comentarios  en  C.  El  significado  de 
los  cuantificadores  variables  no  es  cambiado  en  otro  modo,  justo  el  numero 
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preferido  de  casamientos.  No  confundas  el  uso  de  las  interrogaciones  con 
su  uso  como  un  cuantificador  mas.  Ya  que  tiene  dos  usos,  a  veces  puede 
parecer  doble,  como  en 

\d??\d 

el  cual  empareja  un  dfgito  normalmente,  pero  puede  casar  dos  si  ese  el 
unico  modo  de  casar  el  resto  del  patron. 

Si  se  define  la  opcion  PCRE_UNGREEDY  (la  cual  no  es  posible  en  Perl) 
entonces  los  cuantific adores  no  son  voraces  por  defecto,  pero  uno  puede 
serlo  seguido  por  una  interrogacion.  En  otras  palabras,  invierte  la  conducta 
por  defecto. 

Cuando  un  subpatron  entre  parentesis  es  cuantificado  con  un  nurnero  mmimo 
de  repeticiones  superior  a  uno  o  con  un  lfmite  maximo,  se  necesita  mas 
almacenamiento  para  compilar  el  patron,  en  proporcion  al  tamano  del  mfnimo 
o  del  maximo. 

Si  un  patron  empieza  con  .*  o  .  { 0, }  y  la  opcion  PCRE_DOTALL  (equivalente 
a  Is  del  Perl)  es  definida,  esta  permitiendo  el .  para  casar  nuevas  li'neas, 
entonces  el  patron  es  anclado  implfcitamente.  PCRE  trata  tales  patrones 
como  si  estuvieran  precedidos  por  \A.  En  los  casos  donde  se  conoce  que  la 
cadena  de  entrada  no  contiene  nuevas  lfneas,  es  conveniente  definir 
PCRE_DOTALL  cuando  el  patron  empieza  con  .*  para  obtener  esta  optimizacion 
o  usar  A  para  indicar  explfcitamente  anclamiento. 

Cuando  un  subpatron  capturado  es  repetido,  el  valor  capturado  es  la 
subcadena  que  empareja  la  iteration  final.  Por  ejemplo,  el  patron 

(tweedle[dume]  { 3  }\s*)+ 

con  la  cadena  de  entrada  "tweedledum  tweedledee"  el  valor  de  la  subcadena 
capturada  es  "tweedledee".  Sin  embargo,  si  hay  subpatrones  capturados 
anidadamente,  los  valores  capturados  correspondientes  pueden  haber  sido 
definidos  en  las  iteraciones  anteriores.  Por  ejemplo,  despues  de  casar 
"aba"  con 

/(al(b))+/ 

el  valor  de  la  segunda  subcadena  capturada  es  "b". 

REFERENCIAS  ATRAS 

Fuera  de  una  clase  caracter,  una  barra  invertida  seguida  por  un  digito 
mayor  que  cero  (y  posiblemente  mas  dfgitos)  es  una  referencia  atras  a  un 
subpatron  capturado  antes  (a  su  izquierda)  en  el  patron,  siempre  que  haya 
habido  tantos  parentesis  a  la  izquierda  capturados. 
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Sin  embargo,  si  el  numero  decimal  seguido  por  la  barra  invertida  es  menor 
que  diez,  siempre  es  tornado  como  una  referenda  atras,  y  da  error  solo  si 
no  hay  los  suficientes  subpatrones  capturados  en  todo  el  patron.  En  otras 
palabras,  los  parentesis  que  son  referidos  no  necesitan  estar  a  la 
izquierda  de  la  referencia  para  un  numero  menor  de  diez.  Examina  la  section 
anterior  titulada  "Barra  invertida"  para  mas  detalles  del  manejo  de  los 
dfgitos  con  la  barra  invertida. 

Una  referencia  atras  empareja  si  casa  el  subpatron  capturado  en  el  actual 
punto  de  la  cadena  de  entrada,  mejor  que  casar  cualquier  subpatron  de  la 
misma.  Asf  el  patron 

(senslrespons)e  and  Mibility 

casa  con  "sense  and  sensibility"  y  "response  and  responsi  bility",  pero 
no  "sense  and  responsibility".  Si  el  casamiento  con  la  distincion  entre 
minusculas  y  mayusculas  esta  activado  en  el  momento  de  la  referencia  atras, 
entonces  la  distincion  de  las  letras  es  relevante.  Por  ejemplo, 

((?i)rah)\s+\l 

casa  con  "rah  rah"  y  "RAH  RAH",  pero  no  "RAH  rah",  pero  el  subpatron 
capturado  originalmente  es  emparejado  sin  la  distincion. 

Puede  haber  mas  de  una  referencia  atras  en  el  mismo  subpatron.  Si  un 
subpatron  no  ha  sido  usado  en  un  emparejamiento  particular,  entonces 
cualquier  referencia  atras  siempre  fallara.  Por  ejemplo,  el  patron 

(al(bc))\2 

fallara  siempre  si  inicia  a  casar  con  "a"  mejor  que  con  "be".  Ya  que  puede 
haber  hasta  99  references  atras,  todos  los  dfgitos  seguidos  por  una  barra 
invertida  son  tornados  como  parte  de  numero  potencial  de  referencias  atras. 

Si  el  patron  continua  con  un  caracter  de  dfgito,  entonces  algun  delimitador 
debe  ser  usado  para  terminar  la  referencia  atras.  Si  la  option  PCRE_EXTENDED 
es  definida,  este  puede  ser  el  espacio  en  bianco.  De  otro  modo  un  comentario 
vacio  puede  ser  usado. 

Una  referencia  atras  ocurre  dentro  del  parentesis  al  cual  rehere,  falla 
cuando  el  subpatron  es  usado  por  primera  vez,  asf  por  ejemplo,  (a\l)  nunca 
emparejara.  Sin  embargo,  tal  referencia  puede  ser  util  dentro  de  los 
subpatrones  repetidos.  Por  ejemplo,  el  patron 

(alb\l)+ 

casa  con  cualquier  numero  de  "a"s  y  tambien  con  "aba",  "ababaa"  etc.  Para 
cada  iteration  del  subpatron,  la  referencia  atras  casa  la  cadena  de 
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caracteres  correspondiente  a  la  iteracion  anterior.  Para  que  esto  trabaje, 
el  patron  debe  ser  tal  que  la  primera  iteracion  no  necesite  casar  la  referencia 
atras.  Esto  puede  hacerse  usando  alternativas,  como  en  el  ejemplo  anterior, 
o  por  medio  de  cuantificadores  con  un  numero  mrnimo  de  cero. 

SENTENCIAS 

Una  sentencia  es  un  test  sobre  los  caracteres  siguiendo  o  precediendo  el 
punto  actual  de  emparejamiento  que  no  consume  caracteres.  Las  sentencias 
codificadas  como  \b,  \B,  \A,  \Z,  \z,  A  y  $  son  descritas  despues.  Las 
sentencias  mas  complejas  son  codificadas  como  subpatrones.  Hay  dos  clases: 
aquellas  que  condicionan  mas  adelante  de  la  position  actual  en  la  cadena 
de  entrada  (lookahead)y  las  que  lo  hacen  en  este  punto  (lookbehind). 

Un  subpatron  de  sentencia  es  emparejado  del  modo  tfpico,  excepto  que  no 
hace  que  el  punto  actual  de  emparejamiento  cambie.  Sentencias  que  condicionan 
mas  adelante  empiezan  con  (?=  para  sentencias  afirmativas  y  (?!  para  las 
negativas 


\w+(?=;) 


empareja  una  palabra  seguida  por  un  punto  y  coma,  pero  no  incluye  el 
punto  y  coma  en  el  casamiento,  y 

foo(?!bar) 

casa  cualquier  ocurrencia  de  "foo"  que  no  es  seguida  por  "bar".  Ten  en  cuenta 
que  el  patron  similar 

(?!foo)bar 

no  encuentra  una  ocurrencia  de  "bar"  que  es  precedida  por  algo  que  no  sea  "foo"; 
encuentra  cualquier  ocurrencia  de  "bar",  ya  que  la  sentencia  (?!foo)  es  siempre 
verdadera  cuando  los  tres  primeros  caracteres  son  "bar".  Una  sentencia  en  el 
punto  actual  es  necesaria  para  realizar  este  efecto.  Las  sentencias  de  punto 
actual  empiezan  con  (?<=  para  sentencias  afirmativas  y  (?<!  para  las 
negativas.  Por  ejemplo, 

(?<!foo)bar 

encuentra  una  ocurrencia  de  "bar"  que  no  es  precedida  por  "foo". 

Los  contenidos  de  un  sentencia  de  punto  actual  estan  limitados  para  que  todas 
las  cadenas  que  emparejen  deban  tener  una  longitud  fijada.  Sin  embargo,  si 
hay  varias  alternativas,  no  todas  tienen  que  tener  la  misma  longitud.  Asi 

(?<=bullockldonkey) 

es  permitido,  pero 
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(?<!dogs?lcats?) 

da  error  en  tiempo  de  compilacion.  Opciones  que  emparejen  diferentes 
longitudes  de  cadenas  son  permitidas  solo  a  nivel  superior  de  la  sentencia 
de  punto  actual.  Esta  es  una  extension  comparada  con  Perl  5.005,  la  cual 
requiere  que  todas  las  opciones  a  casar  tengan  la  misma  longitud.  Una 
sentencia  como 

(?<=ab(clde)) 

no  es  permitida,  ya  que  sus  opciones  a  nivel  superior  pueden  casar  dos 
longitudes  diferentes,  pero  es  aceptable  si  se  rescribe  para  usar  dos 
opciones  a  nivel  superior: 

(?<=abclabde) 

La  implementacion  de  sentencias  de  punto  actual  es,  para  cada  altemativa, 
mover  temporalmente  la  posicion  actual  hacia  atras  por  la  longitud  fijada 
e  intentar  casar.  Si  no  hay  suficientes  caracteres  antes  de  la  posicion 
actual,  fallara.  Las  sentencias  de  punto  actual  en  union  con  subpatrones  de 
solo  una  vez  pueden  ser  particularmente  utiles  para  emparejamientos  de  finales 
de  cadenas;  un  ejemplo  es  dado  al  final  de  la  seccion  sobre  subpatrones 
de  una  sola  vez. 

Varias  sentencias  (de  cualquier  tipo)  pueden  suceder  consecutivamente. 

Por  ejemplo, 

(?<=\d  { 3  })(?<  !999)foo 

empareja  "foo"  precedido  por  tres  dfgitos  que  no  sean  "999". 

Ademas,  las  sentencias  puede  ser  anidadas  en  cualquier  combination.  Por 
ejemplo, 

(?<=(?<  !foo)bar)baz 

empareja  una  ocurrencia  de  "baz"  que  es  precedida  por  "bar"  la  cual  no  sea 
precedida  por  "foo". 

Los  subpatrones  de  sentencias  no  son  subpatrones  capturados,  y  no  pueden 
ser  repetidos,  ya  que  no  tiene  sentido  la  misma  cosa  varias  veces.  Si  una 
sentencia  contiene  subpatrones  capturados  dentro  de  ella,  estos  son  siempre 
contados  para  el  proposito  de  la  numeracion  de  los  subpatrones  capturados 
en  todo  el  patron.  Las  subcadenas  capturadas  son  tenidas  en  cuenta  para 
las  sentencias  afirmativas,  pero  no  para  las  negativas  (no  tiene  sentido). 

El  contador  de  sentencias  llega  hasta  un  maximo  de  doscientos  subpatrones 
con  parentesis. 
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SUBPATRONES  DE  UNA  SOLA  VEZ 

Maximizando  y  minimizando  las  repeticiones  para  ver  si  un  numero  diferente 
de  estas  permite  al  resto  del  patron  emparejar,  causa  multiples  evaluaciones 
de  la  cadena  de  entrada.  A  veces  es  util  prevenir  esto,  cambiando  el  patron 
o  provocando  que  la  repeticion  falle  pronto,  cuando  el  creador  del  patron 
conoce  que  no  hay  puntos  en  comun. 

Considera,  por  ejemplo,  el  patron  \d+foo  cuando  se  aplica  a  esta  cadena  de 
entrada 

123456bar 

Despues  de  emparejar  los  seis  dfgitos  falla  al  emparejar  "foo",  la  accion 
normal  del  casamiento  es  intentar  otra  vez  con  solo  cinco  dfgitos  que 
emparejen  con  el  elemento  \d+,  y  entonces  con  cuatro,  y  asf,  antes  de  fallar. 
Subpatrones  de  una  sola  vez  dan  el  modo  de  especificar  que  una  parte  del 
patron  tiene  que  emparejar,  no  es  re-evaluado  de  esta  manera,  asf  el 
casamiento  fallara  al  emparejar  "foo"  la  primera  vez.  La  notacion  es  otra 
clase  de  parentesis  especial,  iniciado  con  (?gt;  como  en  este  ejemplo: 

(?>\d+)bar 

Esta  clase  de  parentesis  "bloquean"  la  parte  del  patron  que  tiene  que 
ser  emparejada  una  vez  y  un  fallo  impide  que  la  re-evalue. 

Una  description  alternativa  es  que  un  subpatron  de  este  tipo  case  los 
caracteres  de  la  cadena  que  un  patron  fijo  emparejarfa,  si  estuviera  anclado 
en  el  punto  actual  de  la  cadena  de  entrada. 

Subpatrones  de  una  sola  vez  no  son  subpatrones  capturados.  Estos  casos  tal 
como  el  ejemplo  anterior  pueden  ser  interpretado  como  de  una  repeticion 
maximizada  que  debe  tragar  todo  lo  que  pueda. 

Por  esto,  mientras  ambos  \d+  y  \d?  estan  preparados  para  ajustar  el  numero 
de  dfgitos  que  emparejan  para  hacer  que  el  resto  del  patron  case,  (?>\d+) 
solo  puede  emparejar  un  secuencia  de  dfgitos  entera. 

Esta  construction,  por  supuesto,  puede  contener  subpatrones  arbitriamente 
complicados  y  pueden  estar  anidados. 

Subpatrones  de  una  sola  vez  pueden  usarse  con  sentencias  de  punto  actual 
para  especificar  eficientes  emparejamientos  al  final  de  la  cadena  de  entrada. 
Consideremos  un  patron  sencillo  como  este 

abcd$ 

cuando  se  aplica  a  una  cadena  larga  con  la  cual  no  empareja.  Ya  que  el 
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casamiento  va  de  izquierda  a  derecha,  PCRE  buscara  cada  "a"  en  la  cadena 
y  entonces  vera  si  lo  que  sigue  casa  con  el  resto  del  patron.  Si  el  patron 
se  escribe  asf 

A.*abcd$ 

entonces  el  .*  inicial  casara  primero  la  cadena  entera,  pero  cuando  esto 
falle,  volvera  atras  para  emparejar  todo  menos  el  ultimo  caracter,  entonces 
los  dos  ultimos  y  asf  sucesivamente.  Otra  vez  la  busqueda  de  "a"  cubre  la 
cadena  completa,  de  derecha  a  izquierda,  de  esta  manera  no  se  mejora.  Sin 
embargo,  si  el  patron  fuese  este 

A(?>.*)(?<=abcd) 

entonces  no  hay  vuelta  atras  para  el  elemento  solo  puede  casar  la  cadena 
entera.  La  sentencia  de  punto  actual  subsiguiente  hace  un  test  sencillo 
sobre  los  ultimos  cuatro  caracteres.  Si  falla,  el  casamiento  inmediatamente 
da  un  resultado  negativo.  Para  cadena  largas,  este  acercamiento  da  una 
diferencia  significativa  en  tiempo  de  ejecucion. 

SUBPATRONES  CONDICIONALES 

Es  posible  hacer  que  el  casamiento  procese  un  subpatron  condicionalmente 
o  elegir  entre  dos  subpatrones  alternativos,  dependiendo  del  resultado 
de  una  sentencia  o  si  un  subpatron  capturado  previamente  caso  o  no. 

Las  dos  formas  posibles  de  subpatrones  condicionales  son 

(?(condition)yes-pattern) 

(?(condition)yes-patternlno-pattern) 

Si  la  condicion  es  satisfecha,  el  yes-pattern  es  usado;  sino  el  no-pattern 
es  utilizado  si  existe.  Si  hay  mas  de  dos  alternativas  en  el  subpatron,  se 
produce  un  error  en  tiempo  de  compilacion. 

Hay  dos  clases  de  condiciones.  Si  el  texto  entre  los  parentesis  consiste 
de  una  secuencia  de  dfgitos,  entonces  la  condicion  es  verdadera  si  el 
subpatron  capturado  de  ese  numero  ha  sido  casado  previamente.  Consideremos 
el  siguiente  patron,  contiene  espacios  en  bianco  para  hacerlo  mas  lefble 
(asumimos  la  option  PCRE_EXTENDED)  y  lo  dividimos  en  tres  partes  para 
facilitar  la  discusion: 

(\Q?  [A()]+  (7(1)  \)) 

La  primera  parte  empareja  un  parentesis  opcional  abierto,  y  si  el  caracter 
esta  presente,  lo  define  como  la  primera  subcadena  capturada.  La  segunda 
parte  casa  uno  o  mas  caracteres  que  no  estan  entre  parentesis.  La  tercera 
parte  es  un  subpatron  condicional  que  examina  si  el  primer  conjunto  de 
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parentesis  casa  o  no.  Si  fuera  asf,  esto  es,  si  la  cadena  de  entrada 
empieza  por  un  parentesis  abierto,  la  condicion  es  cierta,  y  el  yes-pattern 
es  ejecutado  y  un  parentesis  de  cierre  es  requerido.  De  otro  modo,  ya  que 
no-pattern  no  esta  presente,  el  subpatron  no  casa  con  nada.  En  otras 
palabras,  este  patron  casa  una  secuencia  de  datos  sin  parentesis 
opcionalmente  limitada  por  ellos. 

Si  la  condicion  no  es  una  secuencia  de  dfgitos,  debe  ser  una  sentencia. 
Esto  puede  ser  una  sentencia  de  mas  adelante  positiva  o  negativa  o  una 
de  punto  actual.  Consideremos  este  patron,  otra  vez  conteniendo  espacios 
en  bianco  sin  significado  y  con  la  segunda  alternativa  en  la  siguiente  lfnea: 


(?(?=[Aa-z]*[a-z]) 

\d { 2 } [a-z] { 3 } -\d { 2 }  I  \d { 2 } -\d{ 2 }-\d{ 2 }  ) 

La  condicion  es  una  sentencia  de  mas  adelante  positiva  que  empareja  una 
secuencia  opcional  de  cualquier  cosas  menos  letras  seguido  por  una  letra. 

En  otras  palabras,  examina  la  presencia  de  al  menos  una  letra  en  la  cadena 
de  entrada.  Si  una  letra  es  encontrada,  la  cadena  es  casada  con  la  primera 
alternativa;  sino  lo  es  con  la  segunda.  Este  patron  casa  cadenas  de  una  de 
estas  dos  formas  dd-aaa-dd  o  dd-dd-dd,  donde  aaa  son  letra  y  dd  son  dfgitos. 

COMENTARIOS 

La  secuencia  (?#  marca  el  inicio  de  un  comentario  el  cual  continua  hasta 
el  primer  parentesis.  Los  parentesis  anidados  no  son  permitidos.  Los 
caracteres  que  forman  un  comentario  no  forman  parte  del  patron  de 
emparejamiento. 

Si  la  opcion  PCRE_EXTENDED  es  definida,  un  caracter  #  fuera  de  una  clase 
caracter  crea  un  comentario  que  continua  hasta  la  proxima  lfnea  del  patron. 

RENDIMIENTO 

Ciertos  elementos  que  pueden  aparecer  en  los  patrones  son  mas  eficientes 
que  otros.  Es  mas  eficiente  usar  una  clase  caracter  como  [aeiou]  que  un 
conjunto  de  alternativas  tal  como  (alelilolu).  En  general,  los  constructores 
mas  sencillos  que  dan  la  conducta  requerida  son,  normalmente,  mas  eficientes. 
El  libro  de  Jeffrey  Friedl  contiene  un  monton  de  discusiones  sobre  la 
optimizacion  de  expresiones  regulares  para  un  rendimiento  eficiente. 

Cuando  un  patron  empieza  con  .*  y  la  opcion  PCRE_DOTALL  esta  definida,  el 
patron  es  anclado  implfcitamente  por  PCRE,  ya  que  solo  puede  casar  el  inicio 
de  la  cadena  de  entrada.  Sin  embargo,  si  PCRE_DOTALL  no  es  definido,  PCRE 
no  puede  hacer  esta  optimizacion,  ya  que  el  meta  caracter  .  no  tiene  porque 
casar  con  una  nueva  lfnea  y  si  la  cadena  de  entrada  contiene  varias  nuevas 
lfneas,  el  patron  puede  emparejar  desde  el  caracter  inmediatamente  siguiente 
a  uno  de  ellos  en  vez  del  inicio.  Por  ejemplo,  el  patron 
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(.*)  second 

casa  la  cadena  de  entrada  "firstVnand  second"  (donde  \n  representa  un  caracter 
de  nueva  lfnea)  con  la  primera  subcadena  capturada  empezando  con  "and". 

En  otras  palabras,  PCRE  tiene  que  intentar  los  casamientos  iniciandolos 
despues  de  cada  nueva  lfnea  en  la  cadena  de  entrada. 

Si  estas  usando  un  patron  con  cadenas  de  entrada  que  no  contienen  nuevas 
lfneas,  el  mejor  rendimiento  se  obtiene  definiendo  PCRE_DOTALL  o  iniciando 
el  patron  con  A.*  para  indicar  anclamiento  explfcito.  Esto  previene  a  PCRE 
tener  que  examinar  toda  la  cadena  de  entrada  buscando  nuevas  lfneas  para 
empezar  de  nuevo. 
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LXXIV.  Funciones  para  expresiones  regulares 

Las  expresiones  regulares  se  usan  en  PHP  para  manipular  cadenas  complejas.  Las  funciones  que 
soportan  expresiones  regulares  son: 

•  ereg() 

•  ereg_replace ') 

•  eregi 3 

•  eregi_replace') 

•  split  3 

En  todas  estas  funciones,  el  primer  argumento  es  una  expresion  regular.  PHP  utiliza  las  expresiones 
regulares  extendidas  de  POSIX,  definidas  en  POSIX  1003.2.  Para  una  description  completa  de  las 
expresiones  regulares  POSIX,  ver  las  paginas  de  manual  de  regex  incluidas  en  el  directorio  regex  de  la 
distribution  de  PHP.  Estan  en  formato  de  pagina  de  manual,  por  lo  que  se  deben  leer  con  una  orden  como 

man  /usr/local/src/regex/regex.7. 


Ejemplo  1.  Ejemplos  de  expresiones  regulares 

ereg ( "abc" , $ string) ; 

/*  Devuelve  true  si  "abc" 

se  encuentra  en  $string.  */ 

ereg (" Aabc" ,$ st ring) ; 

/*  Devuelve  true  si  "abc" 

se  encuentra  al  comienzo  de  $string.  */ 

ereg ( "abc$ " , $ string) ; 

/*  Devuelve  true  si  "abc" 

se  encuentra  al  final  de  $string.  */ 

eregi  (  "  (ozilla .  [23]  | MSIE .3) ", $HTTP_USER_AGENT ) ; 

/*  Devuelve  true  si  el  navegador  cliente 
es  Netscape  2,  3  o  MSIE  3.  */ 

ereg ("([[: alnum :]] +)  ( [ [ : alnum: ] ] +)  ( [ [ :alnum: ]]+)", 

$string, $regs) ; 

/*  Pone  tres  palabras  separadas  por  espacios 
en  $regs[l],  $regs[2]  y  $regs[3].  */ 

$string  =  ereg_replace ( " A " , "<BR>" , $string) ; 

/*  Coloca  la  etiqueta  <BR>  al  comienzo  de  $string.  */ 

$string  =  ereg_replace ( " $ " , "<BR>"  ,  $string)  ; 

/*  Coloca  la  etiqueta  <BR>  al  final  de  $string.  */ 

$string  =  ereg_replace ( " \n" , " " , $string) ; 

/*  Elimina  los  caracteres  fin-de-linea  de  $string.  */ 
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ereg  (PHP3,  PHP  4  >=  4.0.0) 

Coincidencia  de  expresiones  regulares 

int  ereg  (string  pattern,  string  string  [,  array  regs] ) 

Busca  en  string  las  coincidencias  con  la  expresion  regular  pattern. 

Si  se  encuentran  coincidencias  con  subcadenas  entre  parentesis  de  pattern  y  la  funcion  se  ha  llamado 
con  el  tercer  argumento  regs,  las  coincidencias  se  almacenaran  en  los  elementos  de  regs.  $regs[l] 
contendra  la  subcadena  que  empieza  en  el  primer  parentesis  izquierdo;  $regs[2]  la  que  comienza  en  el 
segundo,  etc.  $regs[0]  contendra  una  copia  de  string. 

La  busqueda  diferencia  mayusculas  y  minusculas. 

Devuelve  un  valor  verdadero  si  se  encontro  alguna  coincidencia,  o  falso  in  no  se  encontraron 
coincidencias  u  ocurrio  algun  error. 

El  siguiente  fragmento  de  codigo  toma  una  fecha  en  formato  ISO  (AAAA-MM-DD)  y  la  imprime  en 
formato  DD.MM.AAAA: 

Ejemplo  1.  ereg()  example 

if  (  ereg  (  " ( [ 0-9] { 4 } ) - ( [0-9] {1, 2 } ) - (  [0-9] { 1, 2 } ) " ,  $date,  $regs  )  )  { 

echo  " $regs [ 3 ] . $regs [ 2 ] . $regs [1] " ; 

}  else  { 

echo  "Invalid  date  format:  $date"; 

} 


Ver  tambien  eregL),  ereg_replace  ),  y  eregi_replaceO- 


ereg_replace  (PHP  3,  PHP  4  >=4.0.0) 


reemplaza  expresiones  regulares 


string  ereg_replace  (string  pattern,  string  replacement ,  string  string) 


Esta  funcion  examina  string  buscando  coincidencias  de  pattern,  y  reemplaza  el  texto  encontrado 

con  replacement. 

Devuelve  la  cadena  modificada.  Si  no  hay  coincidencias  que  reemplazar,  devuelve  la  cadena  original. 

Si  pattern  contiene  subcadenas  entre  parentesis,  replacement  puede  contener  subcadenas  de  la 
forma  \\  cifra,  que  seran  reemplazadas  por  el  texto  que  coincide  con  la  subcadena  entre  parentesis  que 
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ocupa  el  lugar  indicado  por  la  cifra;  \\0  produce  el  contenido  total  de  la  cadena.  Se  pueden  usar  hasta 
nueve  subcadenas.  Los  parentesis  pueden  anidarse;  en  este  caso  se  cuentan  los  parentesis  de  apertura. 

Si  no  se  encuentran  coincidencias  en  string,  se  devuelve  string  sin  cambios. 

Por  ejemplo,  el  siguiente  fragmento  de  codigo  imprime  "This  was  a  test"  tres  veces: 

Ejemplo  1.  ereg_replace()  example 

$string  =  "This  is  a  test"; 

echo  ereg_replace (  "  is",  "  was",  $string  ) ; 
echo  ereg_replace  (  "(  )is",  "Wlwas",  $string  )  ; 
echo  ereg_replace (  "((  ) i s ) " ,  "\\2was",  $string  ); 


Ver  tambien  ereg)),  eregi)),  y  eregi_replace )). 

eregi  (PHP  3,  PHP  4  >=  4.0.0) 

coincidencia  de  expresiones  regulates  sin  diferenciar  mayusculas  y  minusculas 

int  eregi  (string  pattern,  string  string  [,  array  regs ]) 

Esta  funcion  es  identica  a  ereg)),  excepto  en  que  ignora  la  distincion  entre  mayusculas  y  minusculas. 
Ver  tambien  ereg)),  ereg_replace)),  y  eregi_replace )). 

eregi_replace  (PHP  3,  PHP  4  >=  4.0.0) 

reemplaza  expresiones  regularse  sin  diferenciar  mayusculas  y  minusculas 

string  eregi_replace  (string  pattern,  string  replacement ,  string  string) 

Esta  funcion  es  identica  a  ereg_replace  )),  excepto  en  que  ignora  la  distincion  entre  mayusculas  y 
minusculas. 

Ver  tambien  ereg)),  eregi)),  y  ereg_replace(). 
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split  (PHP3,  PHP  4  >=  4.0.0) 

divide  la  cadena  en  elementos  de  un  array  segun  una  expresion  regular 

array  split  (string  pattern,  string  string  [,  int  limit]) 

Devuelve  un  array  de  cadenas,  cada  una  de  las  cuales  es  una  subcadena  de  string  formada  al  dividir 
esta  en  los  lfmites  formados  por  la  expresion  regular  pattern.  Si  ocurre  un  error,  devuelve  un  valor 
falso. 

Para  obtener  los  cinco  primeros  campos  de  una  lmea  de  /etc/passwd: 

Ejemplo  1.  split()  example 

$passwd_list  =  split  (  $passwd_line,  5  ); 


Para  examinar  una  fecha  que  puede  estar  delimitada  por  barras,  puntos  o  guiones: 

Ejemplo  2.  split()  example 

$date  =  "04/30/1973";  //  Los  delimitadores  pueden  ser  barras,  puntos  o  guiones 

list (  $month,  $day,  $year  )  =  split (  ' [/.-]',  $date  ) ; 
echo  "Month:  $month;  Day:  $day;  Year:  $year<br>\n" ; 


Observar  que  pattern  distingue  entre  mayusculas  y  minusculas. 

Observar  que  si  no  se  necesita  la  potencia  de  las  expresiones  regulares,  es  mas  rapido  utilizar  explode  )), 
que  no  carga  el  motor  de  expresiones  regulares. 

Por  favor,  observar  que  pattern  es  una  expresion  regular.  Si  se  quiere  dividir  con  alguno  de  los 
caracteres  especiales  de  las  expresiones  regulares,  se  necesita  protegerlo  antes.  Si  pareciera  que  split))  (o 
cualquier  otra  funcion  de  regex)  esta  haciendo  algo  irregular,  lease  el  archivo  regex .  7,  incluido  en  el 
subdirectory  regex  de  la  distribucion  de  PHP.  Esta  en  formato  de  pagina  de  manual,  por  lo  que  para 
leerlo  es  necesaria  una  orden  como  man  /usr/local/src/regex/regex.7. 

Ver  tambien:  explode  ))  e  implode'). 


sql_regcase  (PHP  3,  PHP  4  >=4.0.0) 

construye  una  expresion  regular  para  buscar  coincidencias  sin  diferenciar  mayusculas  y  minusculas 

string  sql_regcase  (string  string) 
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Devuelve  una  expresion  regular  valida  que  coincide  con  string  sin  distinguir  mayusculas  y 
minusculas.  Esta  expresion  es  string  con  cada  caracter  convertido  a  una  expresion  entre  corchetes  que 
contiene  el  caracter  en  mayuscula  y  minuscula,  si  es  posible;  en  caso  contrario,  contiene  el  caracter 
original  dos  veces. 

Ejemplo  1.  sql_regcase()  example 

echo  sql_regcase (  "Foo  bar"  ); 

imprime 

[Ff]  [Oo]  [Oo]  [  ]  [Bb]  [Aa]  [Rr] 


Se  puede  utilizar  para  lograr  coincidencias  que  no  diferencien  mayusculas  de  minusculas  en  productos 
que  solo  soportan  expresiones  regulares  que  si  distinguen. 
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LXXV.  Satellite  CORBA  client  extension 


Aviso 

This  module  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  these 
functions,  these  function  names,  in  concreto  ANYTHING  documented  here  can 
change  in  a  future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this 
module  at  your  own  risk. 


The  Satellite  extension  is  used  for  accessing  CORBA  objects.  You  will  need  to  set  the  idl_directory 
entry  in  php.ini  to  a  path  where  you  store  all  IDL  files  you  use. 


Satellite 


OrbitObject  (unknown) 


Access  CORBA  objects 


new  OrbitObject  (string  ior) 


This  class  provides  access  to  a  CORBA  object.  The  ior  parameter  should  be  a  string  containing  the  IOR 
(Interoperable  Object  Reference)  that  identifies  the  remote  object. 


Ejemplo  1.  Sample  IDL  file 

interface  Mylnterface  { 

void  Setlnfo  (string  info); 
string  GetlnfoO; 

attribute  int  value; 

} 


Ejemplo  2.  PHP  code  for  accessing  Mylnterface 

<?php 

$obj  =  new  OrbitObject  ($ior); 

$ob j->SetInfo  ("A  2GooD  object"); 

echo  $ob j->GetInf o  ( ) ; 

$obj->value  =  42; 

echo  $obj->value; 

?> 


OrbitEnum  (unknown) 

Use  CORBA  enums 

new  OrbitEnum  (string  id) 
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This  class  represents  the  enumeration  identified  with  the  id  parameter.  The  id  can  be  either  the  name  of 
the  enumeration  (e.g  "MyEnum"),  or  the  full  repository  id  (e.g.  "IDL:MyEnum:1.0"). 


Ejemplo  1.  Sample  IDL  file 

enum  MyEnum  { 
a,  b,  c,  d,  e 

}  ; 


Ejemplo  2.  PHP  code  for  accessing  MyEnum 

<?php 

$enum  =  new  OrbitEnum  ("MyEnum"); 

echo  $enum->a;  /*  write  0  */ 
echo  $enum->c;  /*  write  2  */ 
echo  $enum->e;  /*  write  4  */ 

?> 


OrbitStruct  (unknown) 


Use  CORBA  structs 


new  OrbitStruct  (string  id) 


This  class  represents  the  structure  identified  with  the  i  d  parameter.  The  i  d  can  be  either  the  name  of  the 
struct  (e.g  "MyStruct"),  or  the  full  repository  id  (e.g.  "IDL:MyStruct:1.0"). 


Ejemplo  1.  Sample  IDL  file 

struct  MyStruct  { 

short  shortvalue; 
string  stringvalue; 


interface  Somelnter f ace  { 

void  SetValues  (MyStruct  values) ; 
MyStruct  GetValues ()  ; 

} 
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Ejemplo  2.  PHP  code  for  accessing  MyStruct 

<?php 

$obj  =  new  OrbitObject  ($ior) ; 

$initial_values  =  new  OrbitStruct  (" IDL : MyStruct : 1 . 0 ") ; 
$initial_values->shortvalue  =  42; 
$initial_values->stringvalue  =  "HGTTG"; 

$ob j->SetValues  ($initial_values) ; 

$values  =  $ob j->GetValues ( ) ; 

echo  $values->shortvalue; 
echo  $values->stringvalue; 

?> 


satellite_caught_exception  (php  4  >=  4  o  3) 


See  if  an  exception  was  caught  from  the  previous  function 


bool  satellite_caught_exception  ( ) 


This  function  returns  true  if  an  exception  has  been  caught. 

Ejemplo  1.  Sample  IDL  file 

/*  ++?????++  Out  of  Cheese  Error.  Redo  From  Start.  */ 
exception  OutOfCheeseError  { 
int  parameter; 

} 

interface  Anotherlnterf ace  { 

void  AskWhyO  raises  (OutOfCheeseError); 

} 
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Ejemplo  2.  PHP  code  for  handling  CORBA  exceptions 

<?php 

$obj  =  new  OrbitObject  ($ior); 

$ob j->AskWhy ( ) ; 

if  ( satellite_caught_exception ( ) )  { 

if  (  " IDL : OutOfCheeseError : 1 . 0 "  ==  satellite_exception_id ( ) )  { 

$exception  =  satellite_exception_value ( ) ; 
echo  $exception->parameter ; 

} 

} 

?> 


satellite_exception  Jd  (php  4  >=  4 ,0 ,3) 

Get  the  repository  id  for  the  latest  excetpion. 

string  satellite_exception_id  () 


Return  a  repository  id  string.  (E.g.  "IDL:MyException:1.0".)  For  example  usage  see 

satellite_caught_exception() . 


satellite_exception_value  <php  4  >=  4  .o  .3> 

Get  the  exception  struct  for  the  latest  exception 

OrbitStruct  satellite_exception_value  () 


Return  an  exception  struct.  For  example  usage  see  satellite_caught_exception(). 
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LXXVI.  Funciones  Semaforo  y  de  memoria 
compartida 

Este  modulo  provee  funciones  semaforo  utilizando  los  semaforos  de  System  V.  Los  semaforos  pueden 
usarse  para  obtener  acceso  exclusivo  a  algun  recurso  del  ordenador  en  cuestion,  o  para  limitar  el  numero 
de  procesos  que  pueden  usar  un  recurso  simultaneamente. 

Este  modulo  provee  tambien  funciones  de  memoria  compartida,  usando  el  compartimiento  de  memoria 
de  System  V.  La  memoria  compartida  puede  usarse  para  proveer  acceso  a  variables  globales.  Los 
diferentes  demonios  http  e  incluso  otros  programas,  (como  Perl,  C, ...)  son  capaces  de  utilizar  estos 
datos,  para  intercambiarlos  de  modo  global.  Recuerde  que,  la  memoria  compartida  NO  es  segura  para  los 
accesos  simultaneos.  Use  los  semaforos  para  obtener  sincronismo. 


Tabla  1.  Limites  de  la  memoria  compartida  del  SO  Unix 


SHMMAX 

maximo  tamano  de  memoria  compartida, 
normalmente  131072  bytes 

SHMMIN 

minimo  tamano  de  memoria  compartida,  por  lo 
general  1  byte 

SHMMNI 

maxima  cantidad  de  segmentos  de  memoria 
compartida,  normalmente  100 

SHMSEG 

maximo  de  memoria  compartida  por  proceso, 
normalmente  6 
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sem_get  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 

obtiene  la  identification  de  un  semaforo  (semaphore  id) 

int  sem_get  (int  key,  int  [max_acquire] ,  int  [perm]) 


Devuelve:  Un  identificador  positivo  de  semaforo  en  caso  de  exito,  o  falso  en  caso  de  error. 

sem_get()  Devuelve  un  id  que  puede  usarse  para  acceder  al  semaforo  de  System  V  con  la  Have  dada.  El 
semaforo  se  usa  si  es  necesario  usando  los  bits  de  permisos  especificados  en  perm  (por  defecto  0666).  El 
numero  de  procesos  que  pueden  adquirir  el  semaforo  simultaneamente,  se  define  en  max_acquire  (por 
defecto  es  1).  Actualmente  este  valor  se  fija  solo  si  el  proceso  determina  que  es  el  unico  relacionado 
actualmente  al  semaforo. 

Una  segunda  llamada  a  sem_get()  para  la  misma  Have,  devolvera  un  id  de  semaforo  diferente,  pero  con 
ambos  identificadoes,  se  accedera  al  mismo  semaforo. 

Vease  tambien:  sem_acquire ')  y  sem_releaseO- 


sem_acquire  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 

adquiere  un  semaforo,  lo  toma  para  sf 

int  sem_acquire  (int  sem_identifier) 


Devuelve:  Verdadero  si  hay  exito,  falso  si  hay  errores 

sem_acquire()  Produce  un  bloqueo  (de  ser  necesario)  hasta  que  el  semaforo  puede  adquirirse.  Un 
proceso  intentando  adquirir  un  semaforo  ya  adquirido,  se  bloqueara  permanentemente  si  adquiriendo  el 
semaforo,  excede  su  valor  de  max_acquire. 

Despues  de  procesar  una  petition,  cualquier  semaforo  adquirido  por  un  proceso,  que  no  sea 
explfcitamente  liberado,  sera  liberado  automnaticamente,  generando  un  mensaje  de  alerta. 

Vease  tambien:  sem_get\)  and  sem_release)). 


sem_release  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 


release  a  semaphore 


int  sem_release 


(int  sem_identifier) 
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Returns:  true  on  success,  false  on  error 

sem_release()  releases  the  semaphore  if  it  is  currently  acquired  by  the  calling  process,  otherwise  a 
warning  is  generated. 

After  releasing  the  semaphore,  sem_acquire  )  may  be  called  to  re-acquire  it. 

Vease  tambien:  sem_get')  y  sem_acquireO- 


shm_attach  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 


Crea  o  abre  un  segmento  de  memoria  compartida 


int  shm_attach  (int  key  [,  int  memsize  [,  int  perm]]) 


shm_attach()  devuelve  un  identificador  que  puede  usarse  para  acceder  a  la  memoria  compartida  de 
SystemV,  con  la  Have  dada,  la  primera  llamada  creara  el  segmento  de  memoria  compartida  con 
mem_size  de  tamano  (por  defecto:  sysvshm.init_mem  en  el  archivo  de  configuration  o  bien  de  10000 
bytes)  y  los  bits  de  permiso  mas  apropiados  (por  defecto:  0666). 

Una  segunda  llamada  a  shm_attach()  con  la  misma  Have  devolvera  un  id  diferente  de  memoria 
compartida,  pero  ambos  identificadores  acceden  a  la  misma  porcion  de  memoria  compartida.  memsize 
y  perm  seran  ignorados. 


shmdetach  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 


Finaliza  conexion  con  un  segmento  de  memoria  compartida 


int  shm_detach  (int  shm_identifier) 


shm_detach()  finaliza  la  conexion  con  la  memoria  compartida,  especificada  por  el  identificador 
shm_identifier  creado  con  shm_attach ').  Hay  que  recordar  que  la  memoria  compartida  aun  existe 
en  el  sistema  Unix,  y  los  datos  aun  estan  presentes. 


shmremove  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 

Elimina  memoria  compartida  del  sistma  Unix 

int  shm_remove  (int  shm_identifier) 
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Elimina  la  memoria  compartida  de  un  sistema  Unix,  Todos  los  datos  seran  destrufdos. 


shm_put_var  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 

Inserta  o  actualiza  una  variable  en  la  memoria  compartida 

int  shm  put  var  (int  shm_identifier,  int  variable_key ,  mixed  variable) 


Inserta  o  actualiza  una  variable  con  una  Have  variable_key.  Son  validos  todos  los  tipos  de 
variable  (doble,  entera,  cadena,  arreglo). 


shm_get_var  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 

Devuelve  una  variable  de  la  memoria  compartida 

mixed  shm_get_var  (int  id,  int  variable_key) 


shm_get_var()  devuelve  la  variable  con  la  Have  variable_key  dada.  La  variable,  queda  presente  en 
la  memoria  compartida. 


shm_remove_var  (php 3>=  s.o.e,  php 4 >=  4 o o> 

Elimina  una  variable  de  la  memoria  compartida 

int  shm_remove_var  (int  id,  int  variable_key) 


Elimina  la  varible  que  se  corresponde  con  la  Have  variable_key  dada,  liberando  la  memoria  que 
ocupaba  aquella. 
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SESAM/SQL-Server  is  a  mainframe  database  system,  developed  by  Fujitsu  Siemens  Computers, 
Germany.  It  runs  on  high-end  mainframe  servers  using  the  operating  system  BS2000/OSD. 

In  numerous  productive  BS2000  installations,  SESAM/SQL-Server  has  proven  ... 

•  the  ease  of  use  of  Java-,  Web-  and  client/server  connectivity, 

•  the  capability  to  work  with  an  availability  of  more  than  99.99%, 

•  the  ability  to  manage  tens  and  even  hundreds  of  thousands  of  users. 


Now  there  is  a  PHP3  SESAM  interface  available  which  allows  database  operations  via  PHP-scripts. 

Configuration  notes:  There  is  no  standalone  support  for  the  PHP  SESAM  interface,  it  works  only  as 
an  integrated  Apache  module.  In  the  Apache  PHP  module,  this  SESAM  interface  is  configured  using 
Apache  directives. 

Tabla  1.  SESAM  Configuration  directives 


Directive 


Meaning 


php3_sesam_oml 


loai 


Name  of  BS2000  PLAM  library  containing  the 
able  SESAM  driver  modules.  Required  for  using  SI 
functions.  Example: 

php 3_s e s am_oml  $ . SYSLNK . SESAM-SQL . 03 C 


id- 

ESAM 


php3_sesam_conf igf ile 


Name  of  SESAM  application  configuration  file.  R 
quired  for  using  SESAM  functions.  Example: 
php3_sesam_conf  igf  ile  $  SESAM.  SESAM .  CdiNF  .AW 
It  will  usually  contain  a  configuration 
like  (see  SESAM  reference  manual): 

CNF=B 
NAM=K 
NOTYPE 


php3_sesam_mes sage catalog 


Name  of  SESAM  message  catalog  file.  In  most  ca;< 
this  directive  is  not  neccessary.  Only  if  the  SES  AiV  [ 
message  file  is  not  installed  in  the  system's  BS2001 ) 
message  file  table,  it  can  be  set  with  this  directive.  Ex¬ 
ample: 

php3_sesam_messagecatalog  $  .  SYSMES  .  SljSAM- 
SQL. 030 


In  addition  to  the  configuration  of  the  PHP/SESAM  interface,  you  have  to  configure  the 
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SESAM-Database  server  itself  on  your  mainframe  as  usual.  That  means: 

•  starting  the  SESAM  database  handler  (DBH),  and 

•  connecting  the  databases  with  the  SESAM  database  handler 


To  get  a  connection  between  a  PHP  script  and  the  database  handler,  the  cnf  and  nam  parameters  of 
the  selected  SESAM  configuration  file  must  match  the  id  of  the  started  database  handler. 

In  case  of  distributed  databases  you  have  to  start  a  SESAM/SQL-DCN  agent  with  the  distribution 
table  including  the  host  and  database  names. 

The  communication  between  PHP  (running  in  the  POSIX  subsystem)  and  the  database  handler 
(running  outside  the  POSIX  subsystem)  is  realized  by  a  special  driver  module  called  SQLSCI  and 
SESAM  connection  modules  using  common  memory.  Because  of  the  common  memory  access,  and 
because  PHP  is  a  static  part  of  the  web  server,  database  accesses  are  very  fast,  as  they  do  not 
require  remote  accesses  via  ODBC,  JDBC  or  UTM. 

Only  a  small  stub  loader  (SESMOD)  is  linked  with  PHP,  and  the  SESAM  connection  modules  are 
pulled  in  from  SESAM’s  OML  PLAM  library.  In  the  configuration  you  must  tell  PHP  the  name  of  this 
PLAM  library,  and  the  file  link  to  use  for  the  SESAM  configuration  file  (As  of  SESAM  V3.0,  SQLSCI  is 
available  in  the  SESAM  Tool  Library,  which  is  part  of  the  standard  distribution). 

Because  the  SQL  command  quoting  for  single  quotes  uses  duplicated  single  quotes  (as  opposed  to 
a  single  quote  preceded  by  a  backslash,  used  in  some  other  databases),  it  is  advisable  to  set  the 
PHP  Configuration  directives  php3_magic_quotes_gpc  and  php3_magic_quotes_sybase  to  On  for  all 

PHP  scripts  using  the  SESAM  interface. 


Runtime  considerations:  Because  of  limitations  of  the  BS2000  process  model,  the  driver  can  be 
loaded  only  after  the  Apache  server  has  forked  off  its  server  child  processes.  This  will  slightly  slow 
down  the  initial  SESAM  request  of  each  child,  but  subsequent  accesses  will  respond  at  full  speed. 

When  explicitly  defining  a  Message  Catalog  for  SESAM,  that  catalog  will  be  loaded  each  time  the 
driver  is  loaded  (i.e.,  at  the  initial  SESAM  request).  The  BS2000  operating  system  prints  a  message 
after  successful  load  of  the  message  catalog,  which  will  be  sent  to  Apache’s  errorjog  file.  BS2000 
currently  does  not  allow  suppression  of  this  message,  it  will  slowly  fill  up  the  log. 

Make  sure  that  the  SESAM  OML  PLAM  library  and  SESAM  configuration  file  are  readable  by  the 
user  id  running  the  web  server.  Otherwise,  the  server  will  be  unable  to  load  the  driver,  and  will  not 
allow  to  call  any  SESAM  functions.  Also,  access  to  the  database  must  be  granted  to  the  user  id  under 
which  the  Apache  server  is  running.  Otherwise,  connections  to  the  SESAM  database  handler  will  fail. 


Cursor  Types:  The  result  cursors  which  are  allocated  for  SQL  "select  type"  queries  can  be  either 
"sequential"  or  "scrollable".  Because  of  the  larger  memory  overhead  needed  by  "scrollable"  cursors, 
the  default  is  "sequential". 

When  using  "scrollable"  cursors,  the  cursor  can  be  freely  positioned  on  the  result  set.  For  each 
"scrollable"  query,  there  are  global  default  values  for  the  scrolling  type  (initialized  to: 
sesam_seek_next)  and  the  scrolling  offset  which  can  either  be  set  once  by  sesam_seek_row()  or 
each  time  when  fetching  a  row  using  sesam_fetch_row().  When  fetching  a  row  using  a  "scrollable" 
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cursor,  the  following  post-processing  is  done  for  the  global  default  values  for  the  scrolling  type  and 
scrolling  offset: 


Tabla  2.  Scrolled  Cursor  Post-Processing 


Scroll  Type 

Action 

SESAM_SEEK_NEXT 

none 

SESAM_SEEK_PRIOR 

none 

S E S AM_S EEK_F I RS T 

set  scroll  type  to  sesam seek next 

SESAM_SEEK_LAST 

set  scroll  type  to  sesam seek prior 

SESAM_SEEK_ABSOLUTE 

Auto-Increment  internal  offset  value 

S  E  S AM_S E E K_RE L AT I VE 

none,  (maintain  global  default  offset  value,  which 
allows  for,  e.g.,  fetching  each  10th  row  backwards) 

Porting  note:  Because  in  the  PHP  world  it  is  natural  to  start  indexes  at  zero  (rather  than  1),  some 
adaptions  have  been  made  to  the  SESAM  interface:  whenever  an  indexed  array  is  starting  with  index 
1  in  the  native  SESAM  interface,  the  PHP  interface  uses  index  0  as  a  starting  point.  E.g.,  when 
retrieving  columns  with  sesam_fetch_row;),  the  first  column  has  the  index  0,  and  the  subsequent 
columns  have  indexes  up  to  (but  not  including)  the  column  count  ($array["count"]).  When  porting 
SESAM  applications  from  other  high  level  languages  to  PHP,  be  aware  of  this  changed  interface. 
Where  appropriate,  the  description  of  the  respective  php  sesam  functions  include  a  note  that  the 
index  is  zero  based. 


Security  concerns:  When  allowing  access  to  the  SESAM  databases,  the  web  server  user  should 
only  have  as  little  privileges  as  possible.  For  most  databases,  only  read  access  privilege  should  be 
granted.  Depending  on  your  usage  scenario,  add  more  access  rights  as  you  see  fit.  Never  allow  full 
control  to  any  database  for  any  user  from  the  ’net!  Restrict  access  to  php  scripts  which  must 
administer  the  database  by  using  password  control  and/or  SSL  security. 


Migration  from  other  SQL  databases:  No  two  SQL  dialects  are  ever  100%  compatible.  When 
porting  SQL  applications  from  other  database  interfaces  to  SESAM,  some  adaption  may  be  required. 
The  following  typical  differences  should  be  noted: 


•  Vendor  specific  data  types 

Some  vendor  specific  data  types  may  have  to  be  replaced  by  standard  SQL  data  types  (e.g.,  text 
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could  be  replaced  by  varchar (max .  size)). 


•  Keywords  as  SQL  identifiers 

In  SESAM  (as  in  standard  SQL),  such  identifiers  must  be  enclosed  in  double  quotes  (or  renamed). 


•  Display  length  in  data  types 

SESAM  data  types  have  a  precision,  not  a  display  length.  Instead  of  int  (4)  (intended  use: 
integers  up  to  ’9999’),  SESAM  requires  simply  int  for  an  implied  size  of  31  bits.  Also,  the  only 
datetime  data  types  available  in  SESAM  are:  date,  time  (3)  and  timestamp  (3) . 


•  SQL  types  with  vendor-specific  unsigned,  zerofill,  or  auto_increment  attributes 

unsigned  and  zerofill  are  not  supported.  Auto_increment  is  automatic  (use  "INSERT  .  .  . 
values  (*,  ...)"  instead  of ".. .  values  (0,  ...)"  to  take  advantage  of  SESAM-implied 
auto-increment. 


•  int ...  DEFAULT  0000’ 

Numeric  variables  must  not  be  initialized  with  string  constants.  Use  DEFAULT  0  instead.  To 
initialize  variables  of  the  datetime  SQL  data  types,  the  initialization  string  must  be  prefixed  with  the 
respective  type  keyword,  as  in:  create  table  exmpi  (  xtime  timestamp  (3)  default 
TIMESTAMP  '1970-01-01  00:00:00.000'  NOT  NULL  ); 


•  $count  =  xxxx  num  rows(); 

Some  databases  promise  to  guess/estimate  the  number  of  the  rows  in  a  query  result,  even  though 
the  returned  value  is  grossly  incorrect.  SESAM  does  not  know  the  number  of  rows  in  a  query 
result  before  actually  fetching  them.  If  you  REALLY  need  the  count,  try  SELECT  COUNT(...) 
WHERE  ...,  it  will  tell  you  the  number  of  hits.  A  second  query  will  (hopefully)  return  the  results. 


•  DROP  TABLE  thename; 

In  SESAM,  in  the  DROP  TABLE  command,  the  table  name  must  be  either  followed  by  the 
keyword  restrict  or  cascade.  When  specifying  restrict,  an  error  is  returned  if  there  are 
dependent  objects  (e.g.,  VIEWs),  while  with  cascade,  dependent  objects  will  be  deleted  along  with 
the  specified  table. 


Notes  on  the  use  of  various  SQL  types:  SESAM  does  not  currently  support  the  BLOB  type.  A 
future  version  of  SESAM  will  have  support  for  BLOB. 

At  the  PHP  interface,  the  following  type  conversions  are  automatically  applied  when  retrieving  SQL 
fields: 

Tabla  3.  SQL  to  PHP  Type  Conversions 
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SQL  Type 

PHP  Type 

SMALLINT,  INTEGER 

"integer" 

NUMERIC,  DECIMAL,  FLOAT,  REAL,  DOUBLE 

"double" 

DATE,  TIME,  TIMESTAMP 

"string" 

VARCHAR,  CHARACTER 

"string" 

When  retrieving  a  complete  row,  the  result  is  returned  as  an  array.  Empty  fields  are  not  filled  in,  so 
you  will  have  to  check  for  the  existence  of  the  individual  fields  yourself  (use  isset()  or  empty')  to  test 
for  empty  fields).  That  allows  more  user  control  over  the  appearance  of  empty  fields  (than  in  the  case 
of  an  empty  string  as  the  representation  of  an  empty  field). 


Support  of  SESAM’s  "multiple  fields"  feature:  The  special  "multiple  fields"  feature  of  SESAM 
allows  a  column  to  consist  of  an  array  of  fields.  Such  a  "multiple  field"  column  can  be  created  like 
this: 


Ejemplo  1.  Creating  a  "multiple  field"  column 

CREATE  TABLE  multi_f ield_test  ( 
pkey  CHAR (20)  PRIMARY  KEY, 
multi (3)  CHAR (12) 

) 


and  can  be  filled  in  using: 


Ejemplo  2.  Filling  a  "multiple  field"  column 

INSERT  INTO  mult i_f ield_test  (pkey,  multi (2.. 3)  ) 

VALUES  ('Second',  <' f irst_val ' ,  ' second_val ' >) 


Note  that  (like  in  this  case)  leading  empty  sub-fields  are  ignored,  and  the  filled-in  values  are 
collapsed,  so  that  in  the  above  example  the  result  will  appear  as  multi(1  ..2)  instead  of  multi(2..3). 

When  retrieving  a  result  row,  "multiple  columns"  are  accessed  like  "inlined"  additional  columns.  In  the 
example  above,  "pkey"  will  have  the  index  0,  and  the  three  "multi(1  ..3)"  columns  will  be  accessible  as 
indices  1  through  3. 


For  specific  SESAM  details,  please  refer  to  the  SESAM/SQL-Server  documentation  (english) 
(http://its.siemens.de/lobs/its/techinf/oltp/sesam/manuals/index_en.htm)  or  the  SESAM/SQL-Server 
documentation  (german)  (http://its.siemens.de/lobs/its/techinf/oltp/sesam/manuals/index_gr.htm),  both 
available  online,  or  use  the  respective  manuals. 
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sesam_connect  (PHP  3  CVS  only) 


Open  SESAM  database  connection 


bool  sesam_connect  (string  catalog,  string  schema,  string  user) 


Returns  true  if  a  connection  to  the  SESAM  database  was  made,  or  false  on  error. 

sesam_connect()  establishes  a  connection  to  an  SESAM  database  handler  task.  The  connection  is 
always  "persistant"  in  the  sense  that  only  the  very  first  invocation  will  actually  load  the  driver  from  the 
configured  SESAM  OML  PLAM  library.  Subsequent  calls  will  reuse  the  driver  and  will  immediately  use 
the  given  catalog,  schema,  and  user. 

When  creating  a  database,  the  "catalog"  name  is  specified  in  the  SESAM  configuration  directive 

//ADD-SQL-DATABASE-CATALOG-LIST  ENTRY-1  =  *CATALOG(CATALOG-NAME  = 
catalogname,...) 

The  "schema  "  references  the  desired  database  schema  (see  SESAM  handbook). 

The  "user"  argument  references  one  of  the  users  which  are  allowed  to  access  this  "catalog"  I 
"schema  "  combination.  Note  that  "user  "  is  completely  independent  from  both  the  system’s  user  id’s 
and  from  HTTP  user/password  protection.  It  appears  in  the  SESAM  configuration  only. 

See  also  sesam_disconnect 

Ejemplo  1.  Connect  to  a  SESAM  database 

<?php 

if  ( ! sesam_connect  ( "mycatalog" ,  "myschema",  "otto") 
die ("Unable  to  connect  to  SESAM"; 

?> 


sesamdisconnect  (php  3  cvs  omy) 


Detach  from  SESAM  connection 


bool  sesam_disconnect  ( ) 


Returns:  always  true. 

sesam_disconnect()  closes  the  logical  link  to  a  SESAM  database  (without  actually  disconnecting  and 
unloading  the  driver). 
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Note  that  this  isn’t  usually  necessary,  as  the  open  connection  is  automatically  closed  at  the  end  of  the 
script’s  execution.  Uncommitted  data  will  be  discarded,  because  an  implicit  sesam_rollback')  is 
executed. 

sesam_disconnect()  will  not  close  the  persistent  link,  it  will  only  invalidate  the  currently  defined 
"catalog",  "schema  "  and  "user"  triple,  so  that  any  sesam  function  called  after 
sesam_disconnect()  will  fail. 

See  also:  sesam_conncct 

Ejemplo  1.  Closing  a  SESAM  connection 

if  ( sesam_connect  ( "mycatalog" ,  "myschema",  "otto"))  { 

. . .  some  queries  and  stuff  . . . 
sesam_disconnect () ; 

} 


sesam_settransaction  (php  3  cvs  oniy) 

Set  SESAM  transaction  parameters 

bool  sesam_settransaction  (int  isolation_level ,  int  read_only) 


Returns:  true  if  the  values  are  valid,  and  the  settransaction()  operation  was  successful,  false 
otherwise. 

sesam_settransaction()  overrides  the  default  values  for  the  "isolation  level"  and  "read-only"  transaction 
parameters  (which  are  set  in  the  SESAM  configuration  file),  in  order  to  optimize  subsequent  queries  and 
guarantee  database  consistency.  The  overridden  values  are  used  for  the  next  transaction  only. 

sesam_settransaction()  can  only  be  called  before  starting  a  transaction,  not  after  the  transaction  has 
been  started  already. 

To  simplify  the  use  in  php  scripts,  the  following  constants  have  been  predefined  in  php  (see  SESAM 
handbook  for  detailed  explanation  of  the  semantics): 


Tabla  1.  Valid  values  for  "Isolation_Level  "  parameter 


Value 

Constant 

Meaning 

1 

S  E  S  AM_T  X I S  0  L_RE  AD_UN  C  OMM I T 

Read  Uncommitted 

2 

SESAM_TXISOL_READ_COMMITTE 

Read  Committed 
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Value 

Constant 

Meaning 

3 

SESAM_TXISOL_REPEATABLE_RE 

Repeatable  Read 

4 

SESAM_TXISOL_SERIALI  ZABLE 

Serializable 

Tabla  2.  Valid  values  for  "Read_Only"  parameter 


Value 

Constant 

Meaning 

0 

SESAM TXREAD READ WRITE 

Read/Write 

1 

SESAM_TXREAD_READONLY 

Read-Only 

The  values  set  by  sesam_settransaction()  will  override  the  default  setting  specified  in  the  SESAM 
configuration  file 


Ejemplo  1.  Setting  SESAM  transaction  parameters 


<?php 

sesam_settransaction  ( SESAM_TXI SOL_REPEATABLE_READ , 

SESAM_TXREAD_READONLY ) ; 


?> 


sesamcommit  (PHP  3  CVS  only) 

Commit  pending  updates  to  the  SESAM  database 

bool  sesam_commit  ( ) 


Returns:  true  on  success,  false  on  errors 
sesam_commit()  commits  any  pending  updates  to  the  database. 

Note  that  there  is  no  "auto-commit"  feature  as  in  other  databases,  as  it  could  lead  to  accidental  data  loss. 
Uncommitted  data  at  the  end  of  the  current  script  (or  when  calling  sesam_disconnect )))  will  be  discarded 
by  an  implied  sesam_rollback')  call. 

See  also:  sesam_rollback '). 

Ejemplo  1.  Committing  an  update  to  the  SESAM  database 

<?php 
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if  ( sesam_connect  ( "mycatalog" ,  "myschema",  "otto"))  { 

if  (!sesam_execimra  ("INSERT  INTO  mytable  VALUES  (*,  'Small  Test',  <0,  8,  15>)")) 
die ("insert  failed"); 
if  ( !sesam_commit () ) 

die ("commit  failed"); 

} 

?> 


sesam  rollback (PHPscvsomy) 


Discard  any  pending  updates  to  the  SESAM  database 


bool  sesam_rollback  () 


Returns:  true  on  success,  false  on  errors 

sesam_rollback()  discards  any  pending  updates  to  the  database.  Also  affected  are  result  cursors  and 
result  descriptors. 

At  the  end  of  each  script,  and  as  part  of  the  sesam_disconnect ')  function,  an  implied  sesam_rollback()  is 
executed,  discarding  any  pending  changes  to  the  database. 

See  also:  sesam_commit '). 

Ejemplo  1.  Discarding  an  update  to  the  SESAM  database 


<?php 

if  ( sesam_connect  ("mycatalog",  "myschema",  "otto"))  { 

if  ( sesam_execimm  ("INSERT  INTO  mytable  VALUES  (*,  'Small  Test',  <0,  8,  15>)") 
&&  sesam_execimm  ("INSERT  INTO  othertable  VALUES  (*,  'Another  Test',  1)")) 
sesam_commit () ; 

else 

sesam_rollback ( ) ; 

} 

?> 


sesamexecimm  (php  3  CVS  only) 


Execute  an  "immediate"  SQL-statement 
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string  sesam_execimm  (string  query) 


Returns:  A  SESAM  "result  identifier"  on  success,  or  false  on  error. 

sesam_execimm()  executes  an  "immediate"  statement  (i.e.,  a  statement  like  UPDATE,  INSERT  or 
DELETE  which  returns  no  result,  and  has  no  INPUT  or  OUTPUT  variables),  "select  type"  queries  can 
not  be  used  with  sesam_execimm().  Sets  the  affected_rows  value  for  retrieval  by  the 
sesam_affected_rows ')  function. 

Note  that  sesam_query\)  can  handle  both  "immediate"  and  "select-type"  queries.  Use  sesam_execimm() 
only  if  you  know  beforehand  what  type  of  statement  will  be  executed.  An  attempt  to  use  SELECT  type 
queries  with  sesam_execimm()  will  return  $err  [  "sqlstate"  ]  ==  "42SBW". 

The  returned  "result  identifier"  can  not  be  used  for  retrieving  anything  but  the  sesam_affected_rowsO;  it 
is  only  returned  for  symmetry  with  the  sesam_query  [)  function. 

$stmt  =  "INSERT  INTO  mytable  VALUES  ('one',  'two')"; 

$result  =  sesam_execimm  ($stmt); 

$err  =  sesam_diagnostic ( ) ; 

print  ("sqlstate  =  $err [" sqlstate "]." \n" . 

"Affected  rows  =  " . $err [ "rowcount " ] ."  ==  ". 
sesam_af f ected_rows ($result) . "\n" ) ; 


See  also:  sesam_query ')  and  sesam_affected_rows '). 


sesam_query  (PHP  3  CVS  only) 

Perform  a  SESAM  SQL  query  and  prepare  the  result 

string  sesam_query  (string  query  [,  bool  scrollable ]) 


Returns:  A  SESAM  "result  identifier"  on  success,  or  false  on  error. 

A  "result_id"  resource  is  used  by  other  functions  to  retrieve  the  query  results. 

sesam_query()  sends  a  query  to  the  currently  active  database  on  the  server.  It  can  execute  both 
"immediate"  SQL  statements  and  "select  type"  queries.  If  an  "immediate"  statement  is  executed,  then  no 
cursor  is  allocated,  and  any  subsequent  sesam_fetch_row ))  or  sesam_fetch_resultO  call  will  return  an 
empty  result  (zero  columns,  indicating  end-of-result).  For  "select  type"  statements,  a  result  descriptor 
and  a  (scrollable  or  sequential,  depending  on  the  optional  boolean  scrollable  parameter)  cursor  will 
be  allocated.  If  scrollable  is  omitted,  the  cursor  will  be  sequential. 

When  using  "scrollable"  cursors,  the  cursor  can  be  freely  positioned  on  the  result  set.  For  each 
"scrollable"  query,  there  are  global  default  values  for  the  scrolling  type  (initialized  to: 

SESAM_SEEK _ next)  and  the  scrolling  offset  which  can  either  be  set  once  by  sesam_seek_row ')  or  each 

time  when  fetching  a  row  using  sesam_fetch_row(). 
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For  "immediate"  statements,  the  number  of  affected  rows  is  saved  for  retrieval  by  the 
sesam_affected_rows ')  function. 

See  also:  sesam_fetch_rowO  and  sesam_fetch_result'). 

Ejemplo  1.  Show  all  rows  of  the  "phone"  table  as  a  html  table 

<?php 

if  ( ! sesam_connect  ("phonedb",  "demo",  "otto")) 
die  ("cannot  connect"); 

$result  =  sesam_query  ("select  *  from  phone"); 
if  ( ! $result)  { 

$err  =  sesam_diagnostic ( ) ; 
die  ( $err [ "errmsg" ] ) ; 

} 

echo  " <TABLE  BORDER>\n " ; 

//  Add  title  header  with  column  names  above  the  result: 
if  ($cols  =  sesam_f ield_array  ($result) )  { 

echo  "  CTRXTH  COLSPAN=" . $cols [ "count" ]. ">Result : </TH></TR>\n" ; 
echo  "  <TR>\n"; 

for  ($col  =  0;  $col  <  $cols [ "count" ] ;  ++$col)  { 

$colattr  =  $cols[$col]; 

/*  Span  the  table  head  over  SESAM' s  "Multiple  Fields":  */ 
if  ( $colattr [ "count " ]  >  1)  { 

echo  "  <TH  COLSPAN=" . $colattr [ "count" $colattr [ "name" ] . 

" (1 . . " . $colattr [ "count " ] . " ) </TH>\n" ; 

$col  +=  $colattr [ "count" ]  -  1; 

}  else 

echo  "  <TH>"  .  $colattr [ "name" ]  .  "</TH>\n"; 

} 

echo  "  </TR>\n"; 

} 

do  { 

//  Fetch  the  result  in  chunks  of  100  rows  max. 

$ok  =  sesam_fetch_result  ($result,  100)  ; 
for  ($row=0;  $row  <  $ok["rows"];  ++$row)  { 

echo  "  <TR>\n"; 

for  ($col  =  0;  $col  <  $ok [ "cols" ] ;  ++$col)  { 

if  (isset($ok[$col] [ $row] ) ) 

echo  "  <TD>"  .  $ok[$col] [$row]  .  "</TD>\n"; 

}  else  { 

echo  "  <TD>-empty-</TD>\n" ; 

} 

} 

echo  "  </TR>\n"; 

} 

} 

while  ($ok [ "truncated" ] )  {  //  while  there  may  be  more  data 

echo  "</TABLE>\n" ; 

} 

/ /  free  result  id 
sesam_f ree_result ($result) ; 
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?> 


sesamnumf  ields  (php  3  cvs  oniy) 

Return  the  number  of  fields/columns  in  a  result  set 

int  sesam_num_f ields  (string  result_id) 


After  calling  sesam_query  f)  with  a  "select  type"  query,  this  function  gives  you  the  number  of  columns  in 
the  result.  Returns  an  integer  describing  the  total  number  of  columns  (aka.  fields)  in  the  current 
result_id  result  set  or  false  on  error. 

For  "immediate"  statements,  the  value  zero  is  returned.  The  SESAM  "multiple  field"  columns  count  as 
their  respective  dimension,  i.e.,  a  three-column  "multiple  field"  counts  as  three  columns. 

See  also:  sesam_query ')  and  sesam_field_array ')  for  a  way  to  distinguish  between  "multiple  field" 
columns  and  regular  columns. 


sesamf  ield_name  (php  3  cvs  oniy) 

Return  one  column  name  of  the  result  set 

int  sesam_f ield_name  (string  result_id,  int  index) 

Returns  the  name  of  a  field  (i.e.,  the  column  name)  in  the  result  set,  or  false  on  error. 

For  "immediate"  queries,  or  for  dynamic  columns,  an  empty  string  is  returned. 

Nota:  The  column  index  is  zero-based,  not  one-based  as  in  SESAM. 

See  also:  sesam_field_array ').  It  provides  an  easier  interface  to  access  the  column  names  and  types,  and 
allows  for  detection  of  "multiple  fields". 


sesam_diagnostic  php 3 cvs oniy) 

Return  status  information  for  last  SESAM  call 
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array  sesam_diagnostic  () 


Returns  an  associative  array  of  status  and  return  codes  for  the  last  SQL  query/statement/command. 
Elements  of  the  array  are: 


Tabla  1.  Status  information  returned  by  sesam_diagnostic() 


Element 

Contents 

$array["sqlstate"] 

5  digit  SQL  return  code  (see  the  SESAM  manual 
for  the  description  of  the  possible  values  of 
SQLSTATE) 

$array["rowcount"] 

number  of  affected  rows  in  last  update/insert/delete 
(set  after  "immediate"  statements  only) 

$array[  "errmsg"] 

"human  readable"  error  message  string  (set  after 
errors  only) 

$  array  ["errcol"] 

error  column  number  of  previous  error  (0-based;  or 
-1  if  undefined.  Set  after  errors  only) 

$array["errlin"] 

error  line  number  of  previous  error  (0-based;  or  -1 
if  undefined.  Set  after  errors  only) 

In  the  following  example,  a  syntax  error  (E  SEW42AE  ILLEGAL  CHARACTER)  is  displayed  by 
including  the  offending  SQL  statement  and  pointing  to  the  error  location: 

Ejemplo  1.  Displaying  SESAM  error  messages  with  error  position 

<?php 

//  Function  which  prints  a  formatted  error  message, 

//  displaying  a  pointer  to  the  syntax  error  in  the 
/ /  SQL  statement 

function  PrintReturncode  ($exec_str)  { 

$err  =  Sesam_Diagnostic  ( ) ; 

$colspan=4;  //  4  cols  for:  sqlstate,  errlin,  errcol,  rowcount 
if  ($err ["errlin"]  ==  -1) 

--$colspan; 

if  ($err ["errcol"]  ==  -1) 

— $colspan; 

if  ( $err [" rowcount " ]  ==  0) 

— $colspan; 

echo  " <TABLE  BORDER>\n" ; 

echo  "<TRXTH  COLSPAN="  .  $colspan  .  "XFONT  COLOR=red>ERROR :  </FONT> 
html  special  chars  ( $err  [  "errmsg"  ]  )  .  "</THX/TR>\n"  ; 
if  ($err ["errcol"]  >=  0)  { 

echo  " <TRXTD  COLSPAN="  .  $colspan  .  "><PRE>\n"  ; 

$errstmt  =  $exec_str . " \n" ; 

for  ($lin=0;  $errstmt  !=  ++$lin)  { 

if  ($lin  !=  $err [ "errlin" ] )  {  //  $lin  is  less  or  greater  than  errlin 

if  (!($i  =  strchr  ($errstmt,  "\n"))) 
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$i  =  ""; 

$line  =  substr  ($errstmt,  0,  strlen ( $errstmt ) -strlen ( $i ) +1 ) ; 
$errstmt  =  substr($i,  1); 
if  ($line  !=  "\n") 

print  htmlspecialchars  ($line); 

}  else  { 

if  (!  ($i  =  strchr  ($errstmt,  "\n"))) 

$i  = 

$line  =  substr  ($errstmt,  0,  strlen  ($errstmt) -strlen ($i) +1) ; 
$errstmt  =  substr($i,  1); 

for  ($col=0;  $col  <  $err  [  "errcol " ] ;  ++$col) 

echo  ( substr  ( $line,  $col,  1)  ==  "\t")  ?  "\t"  : 
echo  " <FONT  COLOR=REDXBLINK>\\</BLINK></FONT>\n"  ; 

print  "<FONT  COLOR=\ " # 8 8 0 0 0 0 \ . htmlspecialchar s ( $ line ) . "</FONT>" 
for  ($col=0;  $col  <  $err  [  "errcol "] ;  ++$col) 

echo  (substr  ($line,  $col,  1)  ==  "\t")  ?  "\t"  : 

echo  " <FONT  COLOR=REDXBLINK>/ </BLINKx/FONT>\n"  ; 

} 


echo  "  </PREX/TDX/TR>\n" ; 

} 

echo  "<TR>\n"; 

echo  "  <TD>sqlstate="  .  $err  [  " sqlstate " ]  .  "</TD>\n"; 

if  ($err ["errlin"]  !=  -1) 

echo  "  <TD>errlin="  .  $err [ "errlin" ]  .  "</TD>\n"; 

if  ($err ["errcol"]  !=  -1) 

echo  "  <TD>errcol="  .  $err [ "errcol " ]  .  "</TD>\n"; 

if  ( $err [ " rowcount " ]  !=  0) 

echo  "  <TD>rowcount="  .  $err [ "rowcount " ]  .  "</TD>\n"; 

echo  "</TR>\n"; 
echo  "</TABLE>\n" ; 


if  ( ! sesam_connect  ( "mycatalog" ,  "phoneno",  "otto")) 
die  ("cannot  connect") ; 

$stmt  =  "SELECT  *  FROM  phone\n" . 

"  WHERES  LASTNAME=' KRAEMER' \n" . 

"  ORDER  BY  FIRSTNAME"; 
if  (!  ($result  =  sesam_query  ($stmt))) 

PrintReturncode  ($stmt); 

?> 


See  also:  sesam_errormsg  ])  for  simple  access  to  the  error  string  only 
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sesam  f etch_resu It  <php  3  cvs  oniy) 


Return  all  or  part  of  a  query  result 


mixed  sesam_fetch_result  (string  result_id  f,  int  max_rows ]) 


Returns  a  mixed  array  with  the  query  result  entries,  optionally  limited  to  a  maximum  of  max_rows 
rows.  Note  that  both  row  and  column  indexes  are  zero-based. 


Tabla  1.  Mixed  result  set  returned  by  sesam_fetch_result() 


Array  Element 

Contents 

int  $arr["count"] 

number  of  columns  in  result  set  (or  zero  if  this  was 
an  "immediate"  query) 

int  $arr["rows"] 

number  of  rows  in  result  set  (between  zero  and 

max rows) 

boolean  $arr["truncated"] 

true  if  the  number  of  rows  was  at  least 
max_rows,  false  otherwise.  Note  that  even  when 
this  is  true,  the  next  sesam_fetch_result()  call 
may  return  zero  rows  because  there  are  no  more 
result  entries. 

mixed  $arr[col]  [row] 

result  data  for  all  the  fields  at  row(row)  and 
column(col),  (where  the  integer  index  row  is 
between  0  and  $arr  [  "rows"  ]  -1,  and  col  is 
between  0  and  $arr  [  "count"  ]  -1).  Fields  may  be 
empty,  so  you  must  check  for  the  existence  of  a  field 
by  using  the  php  isseU)  function.  The  type  of  the 
returned  fields  depend  on  the  respective  SQL  type 
declared  for  its  column  (see  SESAM  overview  for 
the  conversions  applied).  SESAM  "multiple  fields" 
are  "inlined"  and  treated  like  a  sequence  of  columns. 

Note  that  the  amount  of  memory  used  up  by  a  large  query  may  be  gigantic.  Use  the  max_rows 
parameter  to  limit  the  maximum  number  of  rows  returned,  unless  you  are  absolutely  sure  that  your  result 
will  not  use  up  all  available  memory. 

See  also:  sesam_fetch_rowO,  and  sesam_field_array  ')  to  check  for  "multiple  fields".  See  the  description 
of  the  sesam_queryO  function  for  a  complete  example  using  sesam_fetch_result(). 


sesam  affected  rows  <php  3  cvs  omy) 


Get  number  of  rows  affected  by  an  immediate  query 
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int  sesam_af fected_rows  (string  result_id) 


result_id  is  a  valid  result  id  returned  by  sesam_query '). 

Returns  the  number  of  rows  affected  by  a  query  associated  with  result_id. 

The  sesam_affected_rows()  function  can  only  return  useful  values  when  used  in  combination  with 
"immediate"  SQL  statements  (updating  operations  like  insert,  update  and  delete)  because  SESAM 
does  not  deliver  any  "affected  rows"  information  for  "select  type"  queries.  The  number  returned  is  the 
number  of  affected  rows. 

See  also:  sesam_query  J  and  sesam_execimm ') 

$ result  =  sesam_execimm  ("DELETE  FROM  PHONE  WHERE  LASTNAME  =  ' " . strtoupper  ($name) 
if  ( ! $result)  { 

. . .  error  . . . 

} 

print  sesam_af fected_rows  ($result)  . 

"  entries  with  last  name  " . $name . "  deleted. \n" 


sesamerrormsg  (PHP3CVS  only) 

Returns  error  message  of  last  SESAM  call 
string  sesam_errormsg  () 

Returns  the  SESAM  error  message  associated  with  the  most  recent  SESAM  error. 

if  ( ! sesam_execimm  ($stmt)) 

printf  ("%s<br>\n",  sesam_errormsg ( ) ) ; 

See  also:  sesam_diagnostic')  for  the  full  set  of  SESAM  SQL  status  information 


sesamf  ield_array  (php  3  cvs  oniy) 

Return  meta  information  about  individual  columns  in  a  result 


array  sesam_f ield_array  (string  result_id) 
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result_id  is  a  valid  result  id  returned  by  sesam_querv '). 

Returns  a  mixed  associative/indexed  array  with  meta  information  (column  name,  type,  precision,  ...) 
about  individual  columns  of  the  result  after  the  query  associated  with  result_id. 


Tabla  1.  Mixed  result  set  returned  by  sesam_field_array() 


Array  Element 

Contents 

int  $arr["count"] 

Total  number  of  columns  in  result  set  (or  zero  if  this 
was  an  "immediate"  query).  SESAM  "multiple 
fields"  are  "inlined"  and  treated  like  the  respective 
number  of  columns. 

string  $arr[col]["name"] 

column  name  for  column(col),  where  col  is 
between  0  and  $arr  [ "  count "  ]  -1.  The  returned 
value  can  be  the  empty  string  (for  dynamically 
computed  columns).  SESAM  "multiple  fields"  are 
"inlined"  and  treated  like  the  respective  number  of 
columns,  each  with  the  same  column  name. 

string  $arr[col] ["count"] 

The  "count"  attribute  describes  the  repetition  factor 
when  the  column  has  been  declared  as  a  "multiple 
field".  Usually,  the  "count"  attribute  is  1.  The  first 
column  of  a  "multiple  field"  column  however 
contains  the  number  of  repetitions  (the  second  and 
following  column  of  the  "multiple  field"  contain  a 
"count"  attribute  of  1).  This  can  be  used  to  detect 
"multiple  fields"  in  the  result  set.  See  the  example 
shown  in  the  sesam_queryO  description  for  a 
sample  use  of  the  "count"  attribute. 

string  $arr[col]["type"] 

php  variable  type  of  the  data  for  column(col), 
where  col  is  between  0  and  $arr  [  "count"  ]  -1. 
The  returned  value  can  be  one  of  •  "integer" 

•  "double" 

•  "string" 

depending  on  the  SQL  type  of  the  result.  SESAM 
"multiple  fields"  are  "inlined"  and  treated  like  the 
respective  number  of  columns,  each  with  the  same 
php  type. 
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Array  Element 

Contents 

string  $arr[col]["sqltype"] 

SQL  variable  type  of  the  column  data  for 
column(col),  where  col  is  between  0  and 
$arr  [  "count"  ]  -1.  The  returned  value  can  be  one 
of-  "CHARACTER" 

•  "VARCHAR" 

•  "NUMERIC" 

•  "DECIMAL" 

•  "INTEGER" 

•  "SMALLEST" 

•  "FLOAT" 

•  "REAL" 

•  "DOUBLE" 

•  "DATE" 

•  "TIME" 

•  "TIMESTAMP" 

describing  the  SQL  type  of  the  result.  SESAM 
"multiple  fields"  are  "inlined"  and  treated  like  the 
respective  number  of  columns,  each  with  the  same 
SQL  type. 

string  $arr[col] ["length"] 

The  SQL  "length"  attribute  of  the  SQL  variable  in 
column(col),  where  col  is  between  0  and 
$arr  [  "count"  ]  -1.  The  "length"  attribute  is  used 
with  "CHARACTER"  and  "VARCHAR"  SQL  types 
to  specify  the  (maximum)  length  of  the  string 
variable.  SESAM  "multiple  fields"  are  "inlined"  and 
treated  like  the  respective  number  of  columns,  each 
with  the  same  length  attribute. 

string  $arr[col] ["precision"] 

The  "precision"  attribute  of  the  SQL  variable  in 
column(col),  where  col  is  between  0  and 
$arr  [  "count"  ]  -1.  The  "precision"  attribute  is 
used  with  numeric  and  time  data  types.  SESAM 
"multiple  fields"  are  "inlined"  and  treated  like  the 
respective  number  of  columns,  each  with  the  same 
precision  attribute. 
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Array  Element 

Contents 

string  $arr[col] ["scale"] 

The  "scale"  attribute  of  the  SQL  variable  in 
column(col),  where  col  is  between  0  and 
$arr  [  "count"  ]  -1.  The  "scale"  attribute  is  used 
with  numeric  data  types.  SESAM  "multiple  fields" 
are  "inlined"  and  treated  like  the  respective  number 
of  columns,  each  with  the  same  scale  attribute. 

See  the  sesam_query ')  function  for  an  example  of  the  sesam_field_array()  use. 


sesam  fetch_roW(PHP3cvsomy) 


Fetch  one  row  as  an  array 


array  sesam_fetch_row  (string  result_id  [,  int  whence  [,  int  offset]]) 


Returns  an  array  that  corresponds  to  the  fetched  row,  or  false  if  there  are  no  more  rows. 

The  number  of  columns  in  the  result  set  is  returned  in  an  associative  array  element  $array ["count"]. 
Because  some  of  the  result  columns  may  be  empty,  the  count  ])  function  can  not  be  used  on  the  result  row 
returned  by  sesam_fetch_row(). 

result_id  is  a  valid  result  id  returned  by  sesam_querv ')  (select  type  queries  only!). 

whence  is  an  optional  parameter  for  a  fetch  operation  on  "scrollable"  cursors,  which  can  be  set  to  the 
following  predefined  constants: 


Tabla  1.  Valid  values  for  "whence  "  parameter 


Value 

Constant 

Meaning 

0 

SESAM_SEEK_NEXT 

read  sequentially  (after  fetch,  the 
internal  default  is  set  to 

SESAM SEEK NEXT) 

1 

SESAM_SEEK_PRIOR 

read  sequentially  backwards  (after 
fetch,  the  internal  default  is  set  to 

SESAM SEEK PRIOR) 

2 

SESAM_SEEK_FIRST 

rewind  to  first  row  (after  fetch,  the 
default  is  set  to 

SESAM SEEK NEXT) 

3 

SESAM_SEEK_LAST 

seek  to  last  row  (after  fetch,  the 
default  is  set  to 

SESAM_SEEK_PRIOR) 
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Value 

Constant 

Meaning 

4 

SESAM_SEEK_ABSOLUTE 

seek  to  absolute  row  number 
given  as  offset  (Zero-based. 
After  fetch,  the  internal  default  is 

set  to  SESAM_SEEK_ABSOLUTE, 

and  the  internal  offset  value  is 

auto-incremented) 

5 

SESAM_SEEK_RELATIVE 

seek  relative  to  current  scroll 
position,  where  offset  can  be  a 
positive  or  negative  offset  value. 

This  parameter  is  only  valid  for  "scrollable"  cursors. 

When  using  "scrollable"  cursors,  the  cursor  can  be  freely  positioned  on  the  result  set.  If  the  whence 
parameter  is  omitted,  the  global  default  values  for  the  scrolling  type  (initialized  to:  SESAM_SEEK_next, 
and  settable  by  sesam_seek_row'))  are  used.  If  whence  is  supplied,  its  value  replaces  the  global  default. 

offset  is  an  optional  parameter  which  is  only  evaluated  (and  required)  if  whence  is  either 
SESAM_SEEK_relative  or  SESAM_SEEK_AB solute.  This  parameter  is  only  valid  for  "scrollable" 
cursors. 

sesam_fetch_row()  fetches  one  row  of  data  from  the  result  associated  with  the  specified  result  identifier. 
The  row  is  returned  as  an  array  (indexed  by  values  between  0  and  $array  [  "count "  ]  -1).  Fields  may  be 
empty,  so  you  must  check  for  the  existence  of  a  field  by  using  the  php  isset")  function.  The  type  of  the 
returned  fields  depend  on  the  respective  SQL  type  declared  for  its  column  (see  SESAM  overview  for  the 
conversions  applied).  SESAM  "multiple  fields"  are  "inlined"  and  treated  like  a  sequence  of  columns. 

Subsequent  calls  to  sesam_fetch_row()  would  return  the  next  (or  prior,  or  n’th  next/prior,  depending  on 
the  scroll  attributes)  row  in  the  result  set,  or  false  if  there  are  no  more  rows. 

Ejemplo  1.  SESAM  fetch  rows 


<?php 

$result  =  sesam_query  ("SELECT  *  FROM  phone\n"  . 

"  WHERE  LASTNAME=' " . st rtoupper ( $name ) . " ' \n" . 
"  ORDER  BY  FIRSTNAME",  1); 

if  ( ! $result)  { 

. . .  error  . . . 

} 

/ /  print  the  table  in  backward  order 
print  " <TABLE  BORDER>\n" ; 

$row  =  sesam_f etch_row  ($result,  SESAM_SEEK_LAST) ; 
while  (is_array  ($row) )  { 

print  "  <TR>\n" ; 

for  ($col  =  0;  $col  <  $row [ "count "] ;  ++$col)  { 

print  "  <TD>" . htralspecialchars  ( $row [ $col ] ) . " </TD>\n" ; 

} 

print  "  </TR>\n" ; 

//  use  implied  SESAM_SEEK_PRIOR 
$row  =  sesam_fetch_row  ($result); 

} 

print  "</TABLE>\n" ; 
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sesam_f ree_result  ($result); 

?> 

See  also:  sesam_fetch_arrayO  which  returns  an  associative  array,  and  sesam_fetch_result'j  which  returns 
many  rows  per  invocation. 


sesamfetcharray  (php  3  cvs  oniy) 


Fetch  one  row  as  an  associative  array 


array  sesam_fetch_array  (string  result_id  [,  int  whence  [,  int  offset]]) 


Returns  an  array  that  corresponds  to  the  fetched  row,  or  false  if  there  are  no  more  rows. 

sesam_fetch_array()  is  an  alternative  version  of  sesam_fetch_row').  Instead  of  storing  the  data  in  the 
numeric  indices  of  the  result  array,  it  stores  the  data  in  associative  indices,  using  the  field  names  as  keys. 

result_id  is  a  valid  result  id  returned  by  sesam_query()  (select  type  queries  only!). 

For  the  valid  values  of  the  optional  whenceand  offset  parameters,  see  the  sesatu_fetch_row ') 
function  for  details. 

sesam_fetch_array()  fetches  one  row  of  data  from  the  result  associated  with  the  specified  result 
identifier.  The  row  is  returned  as  an  associative  array.  Each  result  column  is  stored  with  an  associative 
index  equal  to  its  column  (aka.  field)  name.  The  column  names  are  converted  to  lower  case. 

Columns  without  a  field  name  (e.g.,  results  of  arithmetic  operations)  and  empty  fields  are  not  stored  in 
the  array.  Also,  if  two  or  more  columns  of  the  result  have  the  same  column  names,  the  later  column  will 
take  precedence.  In  this  situation,  either  call  sesam_fetch_row ')  or  make  an  alias  for  the  column. 

SELECT  TBL1.C0L  AS  F00,  TBL2 . COL  AS  BAR  FROM  TBL1 ,  TBL2 


A  special  handling  allows  fetching  "multiple  field"  columns  (which  would  otherwise  all  have  the  same 
column  names).  For  each  column  of  a  "multiple  field",  the  index  name  is  constructed  by  appending  the 
string  "(n)"  where  n  is  the  sub-index  of  the  multiple  field  column,  ranging  from  1  to  its  declared 
repetition  factor.  The  indices  are  NOT  zero  based,  in  order  to  match  the  nomenclature  used  in  the 
respective  query  syntax.  For  a  column  declared  as: 

CREATE  TABLE  ...  (  ...  MULTI (3)  INT  ) 


the  associative  indices  used  for  the  individual  "multiple  field"  columns  would  be  "multi  (1 )  ", 
"multi  (2)  ",  and  "multi  (3)  "  respectively. 

Subsequent  calls  to  sesam_fetch_array()  would  return  the  next  (or  prior,  or  n’th  next/prior,  depending 
on  the  scroll  attributes)  row  in  the  result  set,  or  false  if  there  are  no  more  rows. 
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Ejemplo  1.  SESAM  fetch  array 

<?php 

$result  =  sesam_query  ("SELECT  *  FROM  phone\n"  . 

"  WHERE  LASTNAME=' " . strtoupper ($name) . " ' \n" . 
"  ORDER  BY  FIRSTNAME",  1); 

if  ( ! $result)  { 

. . .  error  . . . 

} 

/ /  print  the  table : 
print  " <TABLE  BORDER>\n" ; 

while  ( ($row  =  sesam_fetch_array  ($result) )  &&  count  ($row)  >  0)  { 

print  "  <TR>\n" ; 

print  "  <TD>" . htmlspecialchars  ( $row [ " f irstname" ] ) . "</TD>\n"; 
print  "  <TD>" . htmlspecialchars  ( $row [ " lastname " ] ) . " </TD>\n" ; 
print  "  <TD>" . htmlspecialchars  ( $row [ "phoneno" ] ) . " </TD>\n" ; 
print  "  </TR>\n" ; 

} 

print  "</TABLE>\n" ; 
sesam_f ree_result  ($result); 

?> 


See  also:  sesam_fetch_rowO  which  returns  an  indexed  array. 


sesamseekrow  (PHP3CVS  only) 

Set  scrollable  cursor  mode  for  subsequent  fetches 

bool  sesam_seek_row  (string  result_id,  int  whence  [,  int  offset ]) 


result_id  is  a  valid  result  id  (select  type  queries  only,  and  only  if  a  "scrollable"  cursor  was  requested 
when  calling  sesam_queryO). 

whence  sets  the  global  default  value  for  the  scrolling  type,  it  specifies  the  scroll  type  to  use  in 
subsequent  fetch  operations  on  "scrollable"  cursors,  which  can  be  set  to  the  following  predefined 
constants: 


Tabla  1.  Valid  values  for  "whence  "  parameter 


Value 

Constant 

Meaning 

0 

SESAM SEEK NEXT 

read  sequentially 

1 

SESAM SEEK PRIOR 

read  sequentially  backwards 

2 

SESAM_SEEK_FIRST 

fetch  first  row  (after  fetch,  the 
default  is  set  to 

sesam_seek_next) 
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Value 

Constant 

Meaning 

3 

SESAM_SEEK_LAST 

fetch  last  row  (after  fetch,  the 

default  is  set  to 

SESAM SEEK PRIOR) 

4 

SESAM_SEEK_AB SOLUTE 

fetch  absolute  row  number  given 
as  offset  (Zero-based.  After 
fetch,  the  default  is  set  to 
SESAM_SEEK_ABSOLUTE,  and  the 
offset  value  is  auto-incremented) 

5 

SESAM_SEEK_RELATIVE 

fetch  relative  to  current  scroll 
position,  where  offset  can  be  a 
positive  or  negative  offset  value 
(this  also  sets  the  default  "offset" 
value  for  subsequent  fetches). 

offset  is  an  optional  parameter  which  is  only  evaluated  (and  required)  if  whence  is  either 
SESAM_SEEK_RELATIVE  Or  SESAM_SEEK_AB SOLUTE. 


sesamf  ree_result  (php  3  cvs  oniy) 

Releases  resources  for  the  query 

int  sesam_free_result  (string  result_id ) 


Releases  resources  for  the  query  associated  with  result_id.  Returns  false  on  error. 
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LXXVIII.  Session  handling  functions 

Session  support  in  PHP  consists  of  a  way  to  preserve  certain  data  across  subsequent  accesses.  This 
enables  you  to  build  more  customized  applications  and  increase  the  appeal  of  your  web  site. 

If  you  are  familiar  with  the  session  management  of  PHPLIB,  you  will  notice  that  some  concepts  are 
similar  to  PHP’s  session  support. 

A  visitor  accessing  your  web  site  is  assigned  an  unique  id,  the  so-called  session  id.  This  is  either  stored 
in  a  cookie  on  the  user  side  or  is  propagated  in  the  URL. 

The  session  support  allows  you  to  register  arbitrary  numbers  of  variables  to  be  preserved  across  requests. 
When  a  visitor  accesses  your  site,  PHP  will  check  automatically  (if  session. auto_start  is  set  to  1)  or  on 
your  request  (explicitly  through  session_start()  or  implicitly  through  session_register'))  whether  a 
specific  session  id  has  been  sent  with  the  request.  If  this  is  the  case,  the  prior  saved  environment  is 
recreated. 

All  registered  variables  are  serialized  after  the  request  finishes.  Registered  variables  which  are  undefined 
are  marked  as  being  not  defined.  On  subsequent  accesses,  these  are  not  defined  by  the  session  module 
unless  the  user  defines  them  later. 

The  track_vars  and  register_globals  configuration  settings  influence  how  the  session  variables 
get  stored  and  restored. 

Nota:  As  of  PHP  4.0.3,  track_vars  is  always  turned  on. 


If  track_vars  is  enabled  and  register_globals  is  disabled,  only  members  of  the  global  associative 
array  $HTTP_SESSION_VARS  can  be  registered  as  session  variables.  The  restored  session  variables 
will  only  be  available  in  the  array  $HTTP_SESSION_VARS. 


Ejemplo  1.  Registering  a  variable  with  track_vars  enabled 

<?php 

session_register ("count") ; 

$HTTP_SESSION_VARS ["count"] ++; 

?> 


If  register_globals  is  enabled,  then  all  global  variables  can  be  registered  as  session  variables  and  the 
session  variables  will  be  restored  to  corresponding  global  variables. 

Ejemplo  2.  Registering  a  variable  with  register_globals  enabled 

<?php 

session_register ("count") ; 

$count++; 

?> 
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If  both  track_vars  and  register_globals  are  enabled,  then  the  globals  variables  and  the 
$HTTP_SESSION_VARS  entries  will  reference  the  same  value. 

There  are  two  methods  to  propagate  a  session  id: 

•  Cookies 

•  URL  parameter 


The  session  module  supports  both  methods.  Cookies  are  optimal,  but  since  they  are  not  reliable  (clients 
are  not  bound  to  accept  them),  we  cannot  rely  on  them.  The  second  method  embeds  the  session  id 
directly  into  URLs. 

PHP  is  capable  of  doing  this  transparently  when  compiled  with  — enable-trans-sid.  If  you  enable 
this  option,  relative  URIs  will  be  changed  to  contain  the  session  id  automatically.  Alternatively,  you  can 
use  the  constant  SID  which  is  defined,  if  the  client  did  not  send  the  appropriate  cookie.  SID  is  either  of 
the  form  session_name=session_id  or  is  an  empty  string. 

The  following  example  demonstrates  how  to  register  a  variable,  and  how  to  link  correctly  to  another  page 
using  SID. 

Ejemplo  3.  Counting  the  number  of  hits  of  a  single  user 

<?php 

session_register  ("count"); 

$count++; 

?> 

Hello  visitor,  you  have  seen  this  page  <?php  echo  $count;  ?>  times. <p> 

<php? 

#  the  <?=SID?>  is  necessary  to  preserve  the  session  id 

#  in  the  case  that  the  user  has  disabled  cookies 
?> 

To  continue,  <A  HREF="nextpage ,php?<?=SID?>">click  here</A> 


The  <?=SID?>  is  not  necessary,  if  — enable-trans-sid  was  used  to  compile  PHP. 

Nota:  Non-relative  URLs  are  assumed  to  point  to  external  sites  and  hence  don’t  append  the  SID,  as 
it  would  be  a  security  risk  to  leak  the  SID  to  a  different  server. 


To  implement  database  storage,  or  any  other  storage  method,  you  will  need  to  use 
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session_set_save_handler)  to  create  a  set  of  user-level  storage  functions. 

The  session  management  system  supports  a  number  of  configuration  options  which  you  can  place  in  your 
php.ini  file.  We  will  give  a  short  overview. 

•  session .  save_handler  defines  the  name  of  the  handler  which  is  used  for  storing  and  retrieving 
data  associated  with  a  session.  Defaults  to  files. 

•  session .  save_path  defines  the  argument  which  is  passed  to  the  save  handler.  If  you  choose  the 
default  files  handler,  this  is  the  path  where  the  files  are  created.  Defaults  to  /tmp. 


Aviso 

If  you  leave  this  set  to  a  world-readable  directory,  such  as  /tmp  (the  default), 
other  users  on  the  server  may  be  able  to  hijack  sessions  by  getting  the  list  of 
files  in  that  directory. 


•  session .  name  specifies  the  name  of  the  session  which  is  used  as  cookie  name.  It  should  only 
contain  alphanumeric  characters.  Defaults  to  phpsessid. 

•  session .  auto_start  specifies  whether  the  session  module  starts  a  session  automatically  on 
request  startup.  Defaults  to  0  (disabled). 

•  session  .  cookie_lifetime  specifies  the  lifetime  of  the  cookie  in  seconds  which  is  sent  to  the 
browser.  The  value  0  means  "until  the  browser  is  closed."  Defaults  to  0. 

•  session  .  serialize_handler  defines  the  name  of  the  handler  which  is  used  to 
serialize/deserialize  data.  Currently,  a  PHP  internal  format  (name  php)  and  WDDX  is  supported 
(name  wddx).  WDDX  is  only  available,  if  PHP  is  compiled  with  WDDX  support  Defaults  to  php. 

•  session .  gc_probability  specifies  the  probability  that  the  gc  (garbage  collection)  routine  is 
started  on  each  request  in  percent.  Defaults  to  1. 

•  session .  gc_maxlifetime  specifies  the  number  of  seconds  after  which  data  will  be  seen  as 
’garbage’  and  cleaned  up. 

•  session .  referer_check  contains  the  substring  you  want  to  check  each  HTTP  Referer  for.  If  the 
Referer  was  sent  by  the  client  and  the  substring  was  not  found,  the  embedded  session  id  will  be 
marked  as  invalid.  Defaults  to  the  empty  string. 

•  session .  entropy_f  ile  gives  a  path  to  an  external  resource  (file)  which  will  be  used  as  an 
additional  entropy  source  in  the  session  id  creation  process.  Examples  are  /dev/random  or 
/dev/urandom  which  are  available  on  many  Unix  systems. 

•  session .  entropy_length  specifies  the  number  of  bytes  which  will  be  read  from  the  file  specified 
above.  Defaults  to  0  (disabled). 

•  session .  use_cookies  specifies  whether  the  module  will  use  cookies  to  store  the  session  id  on  the 
client  side.  Defaults  to  1  (enabled). 

•  session  .  cookie_path  specifies  path  to  set  in  session_cookie.  Defaults  to  /. 

•  session .  cookie_domain  specifies  domain  to  set  in  session_cookie.  Default  is  none  at  all. 

•  session .  cache_limiter  specifies  cache  control  method  to  use  for  session  pages 
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(nocache/private/public).  Defaults  to  nocache. 

session .  cache_expire  specifies  time-to-live  for  cached  session  pages  in  minutes,  this  has  no 
effect  for  nocache  limiter.  Defaults  to  180. 

session .  use_trans_sid  whether  transient  sid  support  is  enabled  or  not  if  enabled  by  compiling 
with  — enable-trans-sid.  Defaults  to  1  (enabled). 

url_rewriter .  tags  spefifies  which  html  tags  are  rewritten  to  include  session  id  if  transient  sid 
support  is  enabled.  Defaults  to  a=href ,  area=href ,  f  rame=src,  input  =  src,  form=fakeentry 

Nota:  Session  handling  was  added  in  PHP  4.0. 
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session  start  (PHP  4  >=  4.0.0) 


Initialize  session  data 


bool  session_start  () 


session_start()  creates  a  session  (or  resumes  the  current  one  based  on  the  session  id  being  passed  via  a 
GET  variable  or  a  cookie). 

This  function  always  returns  true. 

Nota:  This  function  was  added  in  PHP  4.0. 


session_destroy  php  4  >=  4  o  0> 

Destroys  all  data  registered  to  a  session 

bool  session_destroy  () 


session_destroy()  destroys  all  of  the  data  associated  with  the  currc  lit  session. 

This  function  returns  true  on  success  and  false  on  failure  to  destroy  the  session  data. 


sessionname  <php  4  >=  4.0.0) 


Get  and/or  set  the  current  session  name 


string  session_name  ([string  name] ) 


session_name()  returns  the  name  of  the  current  session.  If  name  is  specified,  the  name  of  the  current 
session  is  changed  to  its  value. 

The  session  name  references  the  session  id  in  cookies  and  URLs.  It  should  contain  only  alphanumeric 
characters;  it  should  be  short  and  descriptive  (i.e.  for  users  with  enabled  cookie  warnings).  The  session 
name  is  reset  to  the  default  value  stored  in  session .  name  at  request  startup  time.  Thus,  you  need  to  call 
session_name()  for  every  request  (and  before  session_start()  or  session_register')  are  called). 
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Ejemplo  1.  session_name()  examples 

<?php 

#  set  the  session  name  to  WebsitelD 

$previous_name  =  session_name  ("WebsitelD"); 

echo  "The  previous  session  name  was  $previous_name<p> " ; 
?> 


Nota:  This  function  was  added  in  PHP  4.0. 


session  _module_name  <php  4  >=  4.o.0) 

Get  and/or  set  the  current  session  module 

string  session_module_name  ([string  module ]) 


session_module_name()  returns  the  name  of  the  current  session  module.  If  module  is  specified,  that 
module  will  be  used  instead. 

Nota:  This  function  was  added  in  PHP  4.0. 


session_save_path  (php  4  >=  4.0.o) 

Get  and/or  set  the  current  session  save  path 

string  session_save_path  ([string  path]) 


session_save_path( )  returns  the  path  of  the  current  directory  used  to  save  session  data.  If  path  is 
specified,  the  path  to  which  data  is  saved  will  be  changed. 

Nota:  On  some  operating  systems,  you  may  want  to  specify  a  path  on  a  filesystem  that  handles  lots 
of  small  files  efficiently.  For  example,  on  Linux,  reiserfs  may  provide  better  performance  than  ext2fs. 
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Nota:  This  function  was  added  in  PHP  4.0. 


sessionjd  (PHP  4  >=  4.0.0) 

Get  and/or  set  the  current  session  id 


string  session_id  ([string  id]) 


session_id()  returns  the  session  id  for  the  current  session.  If  id  is  specified,  it  will  replace  the  current 
session  id. 

The  constant  SID  can  also  be  used  to  retrieve  the  current  name  and  session  id  as  a  string  suitable  for 
adding  to  URLs. 


session_register  (PHP  4  >=  4.0.0) 

Register  one  or  more  variables  with  the  current  session 

bool  session_register  (mixed  name  [,  mixed  ...]) 


session_register()  variable  number  of  arguments,  any  of  which  can  be  either  a  string  holding  the  variable 
name  or  an  array  consisting  of  such  variable  names  or  other  arrays.  For  each  encountered  variable  name, 
session_register()  registers  the  global  variable  named  by  it  with  the  current  session. 

This  function  returns  true  when  the  variable  is  successfully  registered  with  the  session. 

Nota:  It  is  not  currently  possible  to  register  resource  variables  in  a  session.  For  example,  you  can  not 
create  a  connection  to  a  database  and  store  the  connection  id  as  a  session  variable  and  expect  the 
connection  to  still  be  valid  the  next  time  the  session  is  restored.  PHP  functions  that  return  a  resource 
are  identified  by  having  a  return  type  of  resource  in  their  function  definitions.  A  list  of  functions  that 
return  resources  are  available  in  the  resource  types  appendix. 


Nota:  This  function  was  added  in  PHP  4.0. 
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session_unregister  (PHP  4  >=  4.0.0) 

Unregister  a  variable  from  the  current  session 

bool  session_unregister  (string  name) 

session_unregister()  unregisters  (forgets)  the  global  variable  named  name  from  the  current  session. 
This  function  returns  true  when  the  variable  is  successfully  unregistered  from  the  session. 

Nota:  This  function  was  added  in  PHP  4.0. 


sessionunset  <php  4  >=  4  o  0) 

Free  all  session  variables 

void  session_unset  () 


The  session_unset()  function  free’s  all  session  variables  currently  registered. 


session  _is_registered  (php  4  >=  4  0  o> 

Find  out  if  a  variable  is  registered  in  a  session 

bool  session_is_registered  (string  name) 


session_is_registered()  returns  true  if  there  is  a  variable  with  the  name  name  registered  in  the  current 
session. 

Nota:  This  function  was  added  in  PHP  4.0. 
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session_get_cookie_params  (php  4  >=  4 .0  .o> 


Get  the  session  cookie  parameters 


array  session_get_cookie_params  () 


The  session_get_cookie_params()  function  returns  an  array  with  the  current  session  cookie  information, 
the  array  contains  the  following  items: 

•  "lifetime"  -  The  lifetime  of  the  cookie. 

•  "path"  -  The  path  where  information  is  stored. 

•  "domain"  -  The  domain  of  the  cookie. 


session_set_cookie_params  <php  4  >=  4.o.o) 


Set  the  session  cookie  parameters 


void  session_set_cookie_params  (int  lifetime  [,  string  path  [,  string 
domain ] ] ) 


Set  cookie  parameters  defined  in  the  php. ini  file.  The  effect  of  this  function  only  lasts  for  the  duration  of 
the  script. 


session_decode  (PHP  4  >=  4.0.0) 

Decodes  session  data  from  a  string 

bool  session_decode  (string  data) 


session_decode()  decodes  the  session  data  in  data,  setting  variables  stored  in  the  session. 
Nota:  This  function  was  added  in  PHP  4.0. 
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session_encode  (PHP  4  >=  4.0.0) 

Encodes  the  current  session  data  as  a  string 

string  session_encode  () 


session_encode()  returns  a  string  with  the  contents  of  the  current  session  encoded  within. 
Nota:  This  function  was  added  in  PHP  4.0. 


session_set_save_handler  {php  4  >=  4.0.0 


Sets  user-level  session  storage  functions 


void  session_set_save_handler  (string  open,  string  close,  string  read, 
string  write,  string  destroy ,  string  gc) 


session_set_save_handler()  sets  the  user-level  session  storage  functions  which  are  used  for  storing  and 
retrieving  data  associated  with  a  session.  This  is  most  useful  when  a  storage  method  other  than  those 
supplied  by  PHP  sessions  is  preferred,  i.e.  Storing  the  session  data  in  a  local  database. 

Nota:  You  must  set  the  configuration  option  session .  save_handler  to  user  in  your  php.ini  file 
for  session  set_save_handler()  to  take  effect. 


Nota:  The  "write"  handler  is  not  executed  until  after  the  output  stream  is  closed.  Thus,  output  from 
debugging  statements  in  the  "write"  handler  will  never  be  seen  in  the  browser.  If  debugging  output  is 
necessary,  it  is  suggested  that  the  debug  output  be  written  to  a  file  instead. 


The  following  example  provides  file  based  session  storage  similar  to  the  PHP  sessions  default  save 
handler  files.  This  example  could  easily  be  extended  to  cover  database  storage  using  your  favorite 
PHP  supported  database  engine. 
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Ejemplo  1.  session_set_save_handler()  example 

<?php 

function  open  ($save_path,  $session_name)  { 
global  $sess_save_path,  $sess_session_name; 

$sess_save_path  =  $save_path; 
$sess_session_name  =  $session_name; 
return (true ) ; 


function  closet)  { 
return (true ) ; 

} 

function  read  ($id)  { 

global  $sess_save_path,  $sess_session_name; 

$sess_file  =  "$sess_save_path/sess_$id" ; 
if  ($fp  =  Sfopen ( $sess_f ile,  "r"))  { 

$sess_data  =  fread($fp,  filesize ($sess_file) ) ; 
return ($sess_data)  ; 

}  else  { 

return  ("  ") ; 

} 


function  write  ($id,  $sess_data)  { 

global  $sess_save_path,  $sess_session_name; 

$sess_file  =  "$sess_save_path/sess_$id" ; 
if  ($fp  =  Sfopen ( $sess_f ile,  "w"))  { 

return  ( fwrite  ( $fp,  $sess_data) ) ; 

}  else  { 

return (false) ; 

} 


function  destroy  ( $ id)  { 

global  $sess_save_path,  $sess_session_name; 

$sess_file  =  "$sess  save  path/sess  $id"; 
return (Sunlink ($sess_file) ) ; 

} 

/********************************************* 

*  WARNING  -  You  will  need  to  implement  some  * 

*  sort  of  garbage  collection  routine  here.  * 

*********************************************  j 

function  gc  ($maxlifetime)  { 


996 


Sessions 


return  true; 

} 

session_set_save_handler  ("open",  "close",  "read",  "write",  "destroy",  "gc"); 
session_start ( ) ; 

/ /  proceed  to  use  sessions  normally 
?> 


session  cache  limiter  (php 4 >=  4.0.3) 


Get  and/or  set  the  current  cache  limiter 


string  session_cache_limiter  ([string  cache_limiter] ) 


session_cache_limiter()  returns  the  name  of  the  current  cache  limiter.  If  cache_limiter  is  specified, 
the  name  of  the  current  cache  limiter  is  changed  to  the  new  value. 

The  cache  limiter  controls  the  cache  control  HTTP  headers  sent  to  the  client.  These  headers  determine 
the  rules  by  which  the  page  content  may  be  cached.  Setting  the  cache  limiter  to  nocache,  for  example, 
would  disallow  any  client-side  caching.  A  value  of  public,  however,  would  permit  caching.  It  can  also 
be  set  to  private,  which  is  slightly  more  restrictive  than  public. 

The  cache  limiter  is  reset  to  the  default  value  stored  in  session .  cache_limiter  at  request  startup 
time.  Thus,  you  need  to  call  session_cache_limiter()  for  every  request  (and  before  session_start ')  is 
called). 

Ejemplo  1.  session_cache_Iimiter()  examples 

<?php 

#  set  the  cache  limiter  to  'private' 

session_cache_limiter ( '  private'  )  ; 

$cache_limiter  =  session_cache_limiter ( ) ; 

echo  "The  cache  limiter  is  now  set  to  $cache_limiter<p>" ; 

?> 


Nota:  This  function  was  added  in  PHP  4.0.3. 
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session_write_close  (php  4  >=  4  o  4) 


Write  session  data  and  end  session 


void  session_write_close  () 


End  the  current  session  and  store  session  data. 

Session  data  is  usually  stored  after  your  script  terminated  without  the  need  to  call  session_write_close(), 
but  as  session  data  is  locked  to  prevent  concurrent  writes  only  one  script  may  operate  on  a  session  at  any 
time.  When  using  framesets  together  with  sessions  you  will  experience  the  frames  loading  one  by  one 
due  to  this  locking.  You  can  reduce  the  time  needed  to  load  all  the  frames  by  ending  the  session  as  soon 
as  all  changes  to  session  variables  are  done. 
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LXXIX.  Shared  Memory  Functions 

Shmop  is  an  easy  to  use  set  of  functions  that  allows  php  to  read,  write,  create  and  delete  UNIX  shared 
memory  segments.  The  functions  will  not  work  on  windows,  as  it  does  not  support  shared  memory.  To 
use  shmop  you  will  need  to  compile  php  with  the  —  enable-shmop  parameter  in  your  configure  line. 

Nota:  The  functions  explained  in  the  chapter  begin  all  with  shm_()  in  PHP  4.0.3,  but  in  PHP  4.0.4 
and  later  versions  these  names  are  changed  to  begin  with  shmop_(). 


Ejemplo  1.  Shared  Memory  Operations  Overview 

<?php 

//  Create  100  byte  shared  memory  block  with  system  id  if  0xff3 
$shm_id  =  shmop_open ( Oxf f 3,  "c",  0644,  100); 

if ( ! $shm_id)  { 

echo  "Couldn't  create  shared  memory  segmentin'1; 

} 

//  Get  shared  memory  block's  size 
$shm_size  =  shmop_size ( $shm_id) ; 

echo  "SHM  Block  Size:  ".$shm_size.  "  has  been  created. \n"; 

/ /  Lets  write  a  test  string  into  shared  memory 

$shm_bytes_written  =  shmop_write ( $shm_id,  "my  shared  memory  block",  0); 
if ($shm_bytes_written  !=  strlen("my  shared  memory  block"))  { 
echo  "Couldn't  write  the  entire  length  of  data\n"; 

} 

//  Now  lets  read  the  string  back 

$my_string  =  shmop_read ( $shm_id,  0,  $shm_size); 

if ( ! $my_string)  { 

echo  "Couldn't  read  from  shared  memory  blockin'1; 

} 

echo  "The  data  inside  shared  memory  was:  " . $my_string . " in" ; 

/ /Now  lets  delete  the  block  and  close  the  shared  memory  segment 
if ( ! shmop_delete ($shm_id) )  { 

echo  "Couldn't  mark  shared  memory  block  for  deletion. 

} 

shmop_close ($shm_id) ; 

?> 
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shmop_open  (php  4  >=  4.o.4> 

Create  or  open  shared  memory  block 

int  shmop_open  (int  key,  string  flags,  int  mode,  int  size ) 


shmop_open()  can  create  or  open  a  shared  memory  block. 

shmop_open()  takes  4  parameters:  key,  which  is  the  system’s  id  for  the  shared  memory  block,  this 
parameter  can  be  passed  as  a  decimal  or  hex.  The  second  parameter  are  the  flags  that  you  can  use: 


•  "a"  for  access  (sets  IPC_EXCL)  use  this  flag  when  you  need  to  open  an  existing  shared  memory 
segment 

•  "c"  for  create  (sets  IPC_CREATE)  use  this  flag  when  you  need  to  create  a  new  shared  memory 
segment. 

The  third  parameter  is  the  mode,  which  are  the  permissions  that  you  wish  to  assign  to  your  memory 
segment,  those  are  the  same  as  permission  for  a  file.  Permissions  need  to  be  passed  in  octal  form  ex. 
0644.  The  last  parameter  is  size  of  the  shared  memory  block  you  wish  to  create  in  bytes. 

Nota:  Note:  the  3rd  and  4th  should  be  entered  as  0  if  you  are  opening  an  existing  memory  segment. 
On  success  shmop_open()  will  return  an  id  that  you  can  use  to  access  the  shared  memory  segment 
you’ve  created. 


Ejemplo  1.  Create  a  new  shared  memory  block 

<?php 

$shm_id  =  shmop_open (OxOfff ,  "c",  0644,  100); 

?> 

This  example  opened  a  shared  memory  block  with  a  system  id  of  OxOfff. 

shmop_read  (php  4  >=  4.o.4) 

Read  data  from  shared  memory  block 

string  shmop_read  (int  shmid,  int  start,  int  count) 
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shmop_read()  will  read  a  string  from  shared  memory  block. 

shmop_read()  takes  3  parameters:  shmid,  which  is  the  shared  memory  block  identifier  created  by 
shmop_open(),  offset  from  which  to  start  reading  and  count  on  the  number  of  bytes  to  read. 


Ejemplo  1.  Reading  shared  memory  block 

<?php 

$shm_data  =  shmop_read ( $shm_id,  0,  50); 
?> 


This  example  will  read  50  bytes  from  shared  memory  block  and  place  the  data  inside  $shm_data. 


shmop_write  (php  4  >=  4,o  ,4) 

Write  data  into  shared  memory  block 

int  shmop_write  (int  shmid,  string  data,  int  offset) 


shmop_write()  will  write  a  string  into  shared  memory  block. 

shmop_write()  takes  3  parameters:  shmid,  which  is  the  shared  memory  block  identifier  created  by 
shmop_open(),  data,  a  string  that  you  want  to  write  into  shared  memory  block  and  offset,  which 
specifies  where  to  start  writing  data  inside  the  shared  memory  segment. 

Ejemplo  1.  Writing  to  shared  memory  block 

<?php 

$shm_bytes_written  =  shmop_write ( $shm_id,  $my_string,  0); 

?> 


This  example  will  write  data  inside  $my_string  into  shared  memory  block,  $shm_bytes_written 
will  contain  the  number  of  bytes  written. 


shmop_size  <php  4  >=  4 .0 ,4) 


Get  size  of  shared  memory  block 
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int  shmop_size  (int  shmid) 


shmop_size()  is  used  to  get  the  size,  in  bytes  of  the  shared  memory  block. 

shmop_size()  takes  the  shmid,  which  is  the  shared  memory  block  identifier  created  by  shmop_open(), 
the  function  will  return  and  int,  which  represents  the  number  of  bytes  the  shared  memory  block  occupies. 


Ejemplo  1.  Getting  the  size  of  the  shared  memory  block 

<?php 

$shm_size  =  shmop_size ( $shm_id) ; 

?> 


This  example  will  put  the  size  of  shared  memory  block  identified  by  $shm_id  into  $shm_size. 

shmop_delete  (php  4  >=  4  o  4) 

Delete  shared  memory  block 

int  shmop_delete  (int  shmid) 

shmop_delete()  is  used  to  delete  a  shared  memory  block. 

shmop_delete()  takes  the  shmid,  which  is  the  shared  memory  block  identifier  created  by  shmop_open(). 
On  success  1  is  returned,  on  failure  0  is  returned. 

Ejemplo  1.  Deleting  shared  memory  block 

<?php 

shmop_delete ($shm_id)  ; 

?> 

This  example  will  delete  shared  memory  block  identified  by  $shm_id. 

shmop_close  (PHP  4  >=  4.0.4) 

Close  shared  memory  block 
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int  shmop_close  (int  shmid) 

shmop_close()  is  used  to  close  a  shared  memory  block. 

shmop_close()  takes  the  shmid,  which  is  the  shared  memory  block  identifier  created  by  shmop_open(). 
Ejemplo  1.  Closing  shared  memory  block 

<?php 

shmop_close ($shm_id) ; 

?> 

This  example  will  close  shared  memory  block  identified  by  $shm_id. 
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LXXX.  Shockwave  Flash  functions 


PHP  offers  the  ability  to  create  Shockwave  Flash  files  via  Paul  Haeberli’s  libswf  module.  You  can 
download  libswf  at  http://reality.sgi.com/grafica/flash/.  Once  you  have  libswf  all  you  need  to  do  is  to 
configure  — with-swf  [=dir]  where  DIR  is  a  location  containing  the  directories  include  and  lib.  The 
include  directory  has  to  contain  the  swf.h  file  and  the  lib  directory  has  to  contain  the  libswf.a  file.  If  you 
unpack  the  libswf  distribution  the  two  files  will  be  in  one  directory.  Consequently  you  will  have  to  copy 
the  files  to  the  proper  location  manually. 

Once  you’ve  successfully  installed  PHP  with  Shockwave  Flash  support  you  can  then  go  about  creating 
Shockwave  files  from  PHP.  You  would  be  surprised  at  what  you  can  do,  take  the  following  code: 

Ejemplo  1.  SWF  example 


<?php 

swf_openfile  ("test.swf",  256,  256,  30,  1,  1,  1)  ; 
swf_ortho2  (-100,  100,  -100,  100) ; 

swf_def ineline  (1,  -70,  0,  70,  0,  .2); 

swf_def inerect  (4,  60,  -10,  70,  0,  0)  ; 
swf_def inerect  (5,  -60,  0,  -70,  10,  0) ; 
swf_addcolor  (0,  0,  0,  0); 

swf_def inef ont  (10,  "Mod"); 

swf_fontsize  (5)  ; 
swf_f ontslant  (10) ; 

swf_def inetext  (11,  "This  be  Flash  wit  PHP!",  1)  ; 

swf_pushmatrix  ( ) ; 
swf_translate  (-50,  80,  0); 
swf_placeob ject  (11,  60); 
swf_popmatrix  (); 

for  ($i  =  0;  $i  <  30;  $i++)  { 

$p  =  $i/ (30-1) ; 
swf  pushmatrix  (); 
swf_scale  (l-($p*.9),  1,  1); 
swf_rotate  (60*$p,  ' z' ) ; 

swf_translate  (20+20*$p,  $p/1.5,  0); 
swf_rotate  (270*$p,  ' z' ) ; 

swf_addcolor  ($p,  0,  $p/1.2,  -$p) ; 

swf_placeob ject  (1,  50); 
swf_placeob ject  (4,  50); 
swf_placeob ject  (5,  50) ; 
swf_popmatrix  (); 
swf_showf rame  (); 

} 

for  ($i  =  0;  $i  <  30;  $i++)  { 

swf_removeob ject  (50) ; 
if  (  ($i%4)  ==  0)  { 

swf_showf rame  (); 

} 
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} 

swf_startdoaction  (); 
swf_actionstop  (); 
swf_enddoaction  (); 

swf_closef ile  (); 

?> 


It  will  produce  the  animation  found  at  the  following  url 
(http://www.designmultimedia.com/swfphp/test.swf). 

Nota:  SWF  support  was  added  in  PHP4  RC2. 
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swfopenf  Me  (php  4  >=  4.o.o) 


Open  a  new  Shockwave  Flash  file 

void  swf_openfile  (string  filename,  float  width,  float  height,  float 
framerate ,  float  r,  float  g,  float  b) 


The  swf_openfile()  function  opens  a  new  file  named  filename  with  a  width  of  width  and  a  height  of 
height  a  frame  rate  of  framerate  and  background  with  a  red  color  of  r  a  green  color  of  g  and  a 
blue  color  of  b. 

The  swf_openfile()  must  be  the  first  function  you  call,  otherwise  your  script  will  cause  a  segfault.  If  you 
want  to  send  your  output  to  the  screen  make  the  filename:  "php://stdout"  (support  for  this  is  in  4.0.1  and 
up). 


swfclosef  Me  (php  4  >=  4.o.o) 

Close  the  current  Shockwave  Flash  file 

void  swf_closef ile  () 


Close  a  file  that  was  opened  by  the  swf_openfile ')  function. 


swflabelf  rame  (php  4  >=  4.0.o) 

Label  the  current  frame 

void  swf_label frame  (string  name) 


Label  the  current  frame  with  the  name  given  by  the  name  parameter. 


swfshowf  rame  (php  4  >=  4  o  0) 


Display  the  current  frame 


void  swf_showf rame  () 
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The  swf_showframe  function  will  output  the  current  frame. 


swfsetf  rame  (php  4  >=  4.o.o) 

Switch  to  a  specified  frame 

void  swf_setframe  (int  framenumber) 


The  swf_setframe()  changes  the  active  frame  to  the  frame  specified  by  framenumber. 


swfgetf  rame  (php  4  >=  4.o.o) 

Get  the  frame  number  of  the  current  frame 

int  swf_getframe  () 


The  swf_getframe()  function  gets  the  number  of  the  current  frame. 


swfmulcolor  (php  4  >=  4  o  0) 

Sets  the  global  multiply  color  to  the  rgba  value  specified 

void  swf_mulcolor  (float  r,  float  g,  float  b,  float  a) 


The  swf_mulcolor()  function  sets  the  global  multiply  color  to  the  rgba  color  specified.  This  color  is 
then  used  (implicitly)  by  the  swf_placeobject(),  swfjnodifyobject ')  and  the  swf_addbuttonrecord() 
functions.  The  color  of  the  object  will  be  multiplied  by  the  rgba  values  when  the  object  is  written  to  the 
screen. 

Nota:  The  rgba  values  can  be  either  positive  or  negative. 
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swfaddcolor  (php  4  >=  4.0.0 


Set  the  global  add  color  to  the  rgba  value  specified 


void  swf_addcolor  (float  r,  float  g,  float  b,  float  a) 


The  swf_addcolor()  function  sets  the  global  add  color  to  the  rgba  color  specified.  This  color  is  then 
used  (implicitly)  by  the  swf_placeobject(),  swfjnodifyobject ')  and  the  swf_addbuttonrecord  )  functions. 
The  color  of  the  object  will  be  add  by  the  rgba  values  when  the  object  is  written  to  the  screen. 

Nota:  The  rgba  values  can  be  either  positive  or  negative. 


swf_placeobject  <php  4  >=  4.o.o) 


Place  an  object  onto  the  screen 


void  swf_placeob ject 


(int  objid,  int  depth) 


Places  the  object  specified  by  objid  in  the  current  frame  at  a  depth  of  depth.  The  objid  parameter 
and  the  depth  must  be  between  1  and  65535. 

This  uses  the  current  mulcolor  (specified  by  swfjnulcolor'))  and  the  current  addcolor  (specified  by 
swf_addcolorp)  to  color  the  object  and  it  uses  the  current  matrix  to  position  the  object. 

Nota:  Full  RGBA  colors  are  supported. 


swfmodifyobject  (php  4  >=  4.o.o) 


Modify  an  object 


void  swf_modifyob ject  (int  depth,  int  how) 


Updates  the  position  and/or  color  of  the  object  at  the  specified  depth,  depth.  The  parameter  how 
determines  what  is  updated,  how  can  either  be  the  constant  MOD_MATRIX  or  MOD_COLOR  or  it  can 
be  a  combination  of  both  (MOD_MATRIXIMOD_COLOR). 
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MOD_COLOR  uses  the  current  mulcolor  (specified  by  the  function  swf_mulcolor'))  and  addcolor 
(specified  by  the  function  swf_addcolor())  to  color  the  object.  MOD_MATRIX  uses  the  current  matrix  to 
position  the  object. 


swfremoveobject  (php  4  >=  4  o  o> 

Remove  an  object 

void  swf_removeob ject  (int  depth) 


Removes  the  object  at  the  depth  specified  by  depth. 


swf  _nextid(PHP4>=4oo) 

Returns  the  next  free  object  id 

int  swf_nextid  () 


The  swf_nextid()  function  returns  the  next  available  object  id. 


swfstartdoaction  (php  4  >=  4.o.o) 

Start  a  description  of  an  action  list  for  the  current  frame 

void  swf_startdoaction  () 


The  swf_startdoaction()  function  starts  the  description  of  an  action  list  for  the  current  frame.  This  must 
be  called  before  actions  are  defined  for  the  current  frame. 


swfactiongotof  rame  <php  4  >=  4.0.0) 

Play  a  frame  and  then  stop 
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void  swf_actiongotof rame  (int  framenumber) 

The  swf_actionGotoFrame()  function  will  go  to  the  frame  specified  by  framenumber,  play  it,  and 
then  stop. 


swfactiongeturl  (pHP4>=4.o.o) 

Get  a  URL  from  a  Shockwave  Flash  movie 

void  swf_actiongeturl  (string  url,  string  target) 

The  swf_actionGetUrl()  function  gets  the  URL  specified  by  the  parameter  url  with  the  target 

target. 


swfactionnextf  rame  (php  4  >=  4.o.o) 

Go  foward  one  frame 


void  swf _act ionnext f rame  () 


Go  foward  one  frame. 


swfactionprevf  rame  (php  4  >=  4  o  o> 

Go  backwards  one  frame 


void  swf_actionprevf rame  () 


swfactionplay  (php  4  >=  4 .0 .0 

Start  playing  the  flash  movie  from  the  current  frame 
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void  swf_actionplay  () 


Start  playing  the  flash  movie  from  the  current  frame. 


swfactionstop  (php  4  >=  4.0.0) 

Stop  playing  the  flash  movie  at  the  current  frame 

void  swf_actionstop  () 


Stop  playing  the  flash  movie  at  the  current  frame. 


swf_actiontogglequality  (php  4  >=  4 .0 ,0) 

Toggle  between  low  and  high  quality 

void  swf_actiontogglequality  () 


Toggle  the  flash  movie  between  high  and  low  quality. 


swfactionwaitforf  rame  (php  4  >=  4.o.0) 

Skip  actions  if  a  frame  has  not  been  loaded 

void  swf_actionwaitforf rame  (int  framenumber ,  int  skipcount) 


The  swf_actionWaitForFrame()  function  will  check  to  see  if  the  frame,  specified  by  the 
framenumber  parameter  has  been  loaded,  if  not  it  will  skip  the  number  of  actions  specified  by  the 
skipcount  parameter.  This  can  be  useful  for  "Loading..."  type  animations. 


swf_actionsettarget  <php  4  >=  4.o.o) 

Set  the  context  for  actions 
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void  swf_actionsettarget  (string  target) 


The  swf_actionSetTarget()  function  sets  the  context  for  all  actions.  You  can  use  this  to  control  other 
flash  movies  that  are  currently  playing. 


swfactiongotolabel  (php  4  >=  4 .0 .0) 

Display  a  frame  with  the  specified  label 

void  swf_actiongotolabel  (string  label) 


The  swf_actionGotoLabel()  function  displays  the  frame  with  the  label  given  by  the  label  parameter 
and  then  stops. 


swfenddoaction  {php  4  >=  4.o.o) 


End  the  current  action 


void  swf_enddoaction  () 


Ends  the  current  action  started  by  the  swf_startdoactionO  function. 


swfdef  ineline  (php  4  >=  4.o.o) 


Define  a  line 


void  swf_def ineline 

float  width) 


(int  objid,  float  xl,  float  yi,  float  x2 , 


float  y2, 


The  swf_defineline()  defines  a  line  starting  from  the  x  coordinate  given  by  xl  and  the  y  coordinate  given 
by  yl  parameter.  Up  to  the  x  coordinate  given  by  the  x2  parameter  and  the  y  coordinate  given  by  the 
y2  parameter.  It  will  have  a  width  defined  by  the  width  parameter. 
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swfdef  inerect  (php  4  >=  4.o.0) 


Define  a  rectangle 


void  swf_def inerect  (int  objld,  float  xl,  float  yi,  float  x2,  float  y2, 
float  width) 


The  swf_definerect()  defines  a  rectangle  with  an  upper  left  hand  coordinate  given  by  the  x,  xl,  and  the  y, 
yl.  And  a  lower  right  hand  coordinate  given  by  the  x  coordinate,  x2,  and  the  y  coordinate,  y2  .  Width 
of  the  rectangles  border  is  given  by  the  width  parameter,  if  the  width  is  0.0  then  the  rectangle  is  filled. 


swfdef  inepoly  (php  4  >=  4.o.o) 


Define  a  polygon 


void  swf_def inepoly  (int  objid,  array  coords,  int  npoints ,  float  width) 


The  swf_definepoly()  function  defines  a  polygon  given  an  array  of  x,  y  coordinates  (the  coordinates  are 
defined  in  the  parameter  coords).  The  parameter  npoints  is  the  number  of  overall  points  that  are 
contained  in  the  array  given  by  coords.  The  width  is  the  width  of  the  polygon’s  border,  if  set  to  0.0 
the  polygon  is  filled. 


swf_startshape  <php  4  >=  4  0  o> 

Start  a  complex  shape 

void  swf_startshape  (int  objid) 


The  swf_startshape()  function  starts  a  complex  shape,  with  an  object  id  given  by  the  objid  parameter. 


swfshapelinesolid  (pHp4>=4.o.o) 


Set  the  current  line  style 


void  swf_shapelinesolid  (float  r,  float  g,  float  b,  float  a,  float  width) 
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The  swf_shapeLineSolid()  function  sets  the  current  line  style  to  the  color  of  the  rgba  parameters  and 
width  to  the  width  parameter.  If  0.0  is  given  as  a  width  then  no  lines  are  drawn. 

swfshapef  illoff  (php  4  >=  4  o  o) 

Turns  off  filling 

void  swf_shapef illoff  () 

The  swf_shapeFillOff()  function  turns  off  filling  for  the  current  shape. 

swfshapefillsolid  (php4>=4oo) 

Set  the  current  fill  style  to  the  specified  color 

void  swf_shapefillsolid  (float  r,  float  g,  float  b,  float  a) 


The  swf_shapeFillSolid()  function  sets  the  current  fill  style  to  solid,  and  then  sets  the  fill  color  to  the 
values  of  the  rgba  parameters. 


swfshapef  illbitmapclip  (php  4  >=  4  00 

Set  current  fill  mode  to  clipped  bitmap 

void  swf_shapef illbitmapclip  (int  bitmapid) 


Sets  the  fill  to  bitmap  clipped,  empty  spaces  will  be  filled  by  the  bitmap  given  by  the  bitmapid 
parameter. 


swfshapef  illbitmaptile  (php  4  >=  4  0  0> 

Set  current  fill  mode  to  tiled  bitmap 
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void  swf_shapef illbitmaptile  (int  bitmapid) 


Sets  the  fill  to  bitmap  tile,  empty  spaces  will  be  filled  by  the  bitmap  given  by  the  bi  tmapi  d  parameter 
(tiled). 


swfshapemoveto  (php  4  >=  4.o.o) 

Move  the  current  position 

void  swf_shapemoveto  (float  x,  float  y) 


The  swf_shapeMoveTo()  function  moves  the  current  position  to  the  x  coordinate  given  by  the  x 
parameter  and  the  y  position  given  by  the  y  parameter. 


swfshapelineto  (php  4  >=  4.o.o) 

Draw  a  line 

void  swf_shapelineto  (float  x,  float  y) 


The  swf_shapeLineTo()  draws  a  line  to  the  x,y  coordinates  given  by  the  x  parameter  &  the  y  parameter. 
The  current  position  is  then  set  to  the  x,y  parameters. 


swfshapecurveto  (php  4  >=  4  o  o> 

Draw  a  quadratic  bezier  curve  between  two  points 

void  swf_shapecurveto  (float  xl,  float  yl,  float  x2,  float  y2) 


The  swf_shapecurveto()  function  draws  a  quadratic  bezier  curve  from  the  x  coordinate  given  by  xl  and 
the  y  coordinate  given  by  yl  to  the  x  coordinate  given  by  x2  and  the  y  coordinate  given  by  y2.  The 
current  position  is  then  set  to  the  x,y  coordinates  given  by  the  x2  and  y2  parameters 
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swf_shapecurveto3  (php  4  >=  4.o.o) 


Draw  a  cubic  bezier  curve 


void  swf_shapecurveto3  (float  xl,  float  yi,  float  x2,  float  y2,  float  x3, 
float  y3) 


Draw  a  cubic  bezier  curve  using  the  x,y  coordinate  pairs  xl,  yl  and  x2,y2  as  off  curve  control  points 
and  the  x,y  coordinate  x3,  y3  as  an  endpoint.  The  current  position  is  then  set  to  the  x,y  coordinate  pair 
given  by  x3,y3. 


swfshapearc  (php  4  >=  4.o.0) 


Draw  a  circular  arc 


void  swf_shapearc  (float  x,  float  y,  float  r,  float  angl,  float  ang2) 


The  swf_shapeArc()  function  draws  a  circular  arc  from  angle  A  given  by  the  angl  parameter  to  angle  B 
given  by  the  ang2  parameter.  The  center  of  the  circle  has  an  x  coordinate  given  by  the  x  parameter  and 
a  y  coordinate  given  by  the  y,  the  radius  of  the  circle  is  given  by  the  r  parameter. 


swfendshape  <php  4  >=  4  o  0) 

Completes  the  definition  of  the  current  shape 

void  swf_endshape  () 


The  swf_endshape()  completes  the  definition  of  the  current  shape. 


swfdef  inefont  <php  4  >=  4  o  o> 


Defines  a  font 


void  swf_def inefont 


(int  font  id, 


string  fontname) 
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The  swf_delinefont()  function  defines  a  font  given  by  the  fontname  parameter  and  gives  it  the  id 
specified  by  the  fon tid  parameter.  It  then  sets  the  font  given  by  fontname  to  the  current  font. 


swfsetfont  (php  4  >=  4.o.o) 

Change  the  current  font 

void  swf_setfont  (int  fontid) 


The  swf_setfont()  sets  the  current  font  to  the  value  given  by  the  fontid  parameter. 


swffontsize  (php  4  >=  4.o.o) 

Change  the  font  size 

void  swf_fontsize  (float  size) 


The  swf_fontsize()  function  changes  the  font  size  to  the  value  given  by  the  size  parameter. 


swffontslant  <php  4  >=  4.o.o) 

Set  the  font  slant 

void  swf_fontslant  (float  slant) 


Set  the  current  font  slant  to  the  angle  indicated  by  the  slant  parameter.  Positive  values  create  a  foward 
slant,  negative  values  create  a  negative  slant. 


swffontt  racking  (php  4  >=  4.o.0) 

Set  the  current  font  tracking 
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void  swf_fonttracking  (float  tracking) 

Set  the  font  tracking  to  the  value  specified  by  the  tracking  parameter.  This  function  is  used  to 
increase  the  spacing  between  letters  and  text,  positive  values  increase  the  space  and  negative  values 
decrease  the  space  between  letters. 

swfgetfontinfo  (php  4  >=  4.0.0 

The  height  in  pixels  of  a  capital  A  and  a  lowercase  x 

array  swf_getfontinfo  () 

The  swf_getfontinfo()  function  returns  an  associative  array  with  the  following  parameters: 

•  Aheight  -  The  height  in  pixels  of  a  capital  A. 

•  xheight  -  The  height  in  pixels  of  a  lowercase  x. 


swfdef  inetext  (php  4  >=  4.0.0 

Define  a  text  string 

void  swf_def inetext  (int  objid,  string  str,  int  docenter ) 


Define  a  text  string  (the  str  parameter)  using  the  current  font  and  font  size.  The  docenter  is  where 
the  word  is  centered,  if  docenter  is  1,  then  the  word  is  centered  in  x. 


swftextwidth  (php  4  >=  4.0.0) 

Get  the  width  of  a  string 

float  swf_textwidth  (string  str) 


The  swf_textwidth()  function  gives  the  width  of  the  string,  str,  in  pixels,  using  the  current  font  and 
font  size. 
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swfdef  inebitmap  (php  4  >=  4.0.0 


Define  a  bitmap 


void  swf_def inebitmap  (int  objid,  string  image_name ) 


The  swf_definebitmap()  function  defines  a  bitmap  given  a  GIF,  JPEG,  RGB  or  FI  image.  The  image  will 
be  converted  into  a  Flash  JPEG  or  Flash  color  map  format. 


swfgetbitmapinfo  (php  4  >=  4.0.0 

Get  information  about  a  bitmap 

array  swf_getbitmapinf o  (int  bitmapid ) 


The  swf_getbitmapinfo()  function  returns  an  array  of  information  about  a  bitmap  given  by  the 
bitmapid  parameter.  The  returned  array  has  the  following  elements: 

•  "size"  -  The  size  in  bytes  of  the  bitmap. 

•  "width"  -  The  width  in  pixels  of  the  bitmap. 

•  "height"  -  The  height  in  pixels  of  the  bitmap. 


swfstartsymbol  <php  4  >=  4.o.o 

Define  a  symbol 

void  swf_startsymbol  (int  objid ) 


Define  an  object  id  as  a  symbol.  Symbols  are  tiny  flash  movies  that  can  be  played  simultaneously.  The 
objid  parameter  is  the  object  id  you  want  to  define  as  a  symbol. 


swfendsymbol  (php  4  >=  4.o.o 

End  the  definition  of  a  symbol 
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void  swf_endsymbol  () 


The  swf_endsymbol()  function  ends  the  definition  of  a  symbol  that  was  started  by  the  swf_startsymbol ') 
function. 


swfstartbutton  (php  4  >=  4.0.0 

Start  the  definition  of  a  button 

void  swf_startbutton  (int  objid,  int  type) 


The  swf_startbutton()  function  starts  off  the  definition  of  a  button.  The  type  parameter  can  either  be 
TYPE_MENUB UTTON  or  TYPE_PUSHBUTTON.  The  TYPE_MENUBUTTON  constant  allows  the 
focus  to  travel  from  the  button  when  the  mouse  is  down,  TYPE_PUSHB UTTON  does  not  allow  the 
focus  to  travel  when  the  mouse  is  down. 


swfaddbuttonrecord  (php  4  >=  4  0  0 

Controls  location,  appearance  and  active  area  of  the  current  button 

void  swf_addbuttonrecord  (int  states,  int  shapeid,  int  depth) 


The  swf_addbuttonrecord()  function  allows  you  to  define  the  specifics  of  using  a  button.  The  first 
parameter,  states,  defines  what  states  the  button  can  have,  these  can  be  any  or  all  of  the  following 
constants:  BSHitTest,  BSDown,  BSOver  or  BSUp.  The  second  parameter,  the  shapeid  is  the  look  of 
the  button,  this  is  usually  the  object  id  of  the  shape  of  the  button.  The  depth  parameter  is  the  placement 
of  the  button  in  the  current  frame. 

Ejemplo  1.  swf_addbuttonrecord()  function  example 

swf_s tart But ton  ($objid,  TYPE_MENUBUTTON) ; 

swf_addButtonRecord  (BSDown | BSOver ,  $buttonImageId,  340); 
swf_onCondition  (MenuEnter) ; 

swf_actionGetUrl  ( "http : / /www . designmultimedia . com" ,  "_levell " ) ; 
swf_onCondition  (MenuExit); 

swf_actionGetUrl  ("",  "_levell"); 
swf_endButton  (); 
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swfoncondition  (php4>=4.o.o) 

Describe  a  transition  used  to  trigger  an  action  list 

void  swf_oncondition  (int  transition) 


The  swf_onCondition()  function  describes  a  transition  that  will  trigger  an  action  list.  There  are  several 
types  of  possible  transitions,  the  following  are  for  buttons  defined  as  TYPE_MENUBUTTON: 

•  IdletoOverUp 

•  OverUptoIdle 

•  OverUptoOverDown 

•  OverDowntoOverUp 

•  IdletoOverDown 

•  OutDowntoldle 

•  MenuEnter  (IdletoOverUplIdletoOverDown) 

•  MenuExit  (OverUptoIdlelOverDowntoIdle) 

For  TYPE_PUSHBUTTON  there  are  the  following  options: 

•  IdletoOverUp 

•  OverUptoIdle 

•  OverUptoOverDown 

•  OverDowntoOverUp 

•  OverDowntoOutDown 

•  OutDowntoOverDown 

•  OutDowntoldle 

•  ButtonEnter  (IdletoOverUplOutDowntoOverDown) 

•  ButtonExit  (OverUptoIdlelOverDowntoOutDown) 


swfendbutton  (php  4  >=  4.o.o) 

End  the  definition  of  the  current  button 

void  swf_endbutton  () 
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The  swf_endButton()  function  ends  the  definition  of  the  current  button. 


swfviewport  (php  4  >=  4.0.0 

Select  an  area  for  future  drawing 

void  swf_viewport  (double  xmin,  double  xmax,  double  ymin,  double  ymax) 


The  swf_viewport()  function  selects  an  area  for  future  drawing  for  xmin  to  xmax  and  ymin  to  ymax, 
if  this  function  is  not  called  the  area  defaults  to  the  size  of  the  screen. 


swf_orthO(PHP4) 

Defines  an  orthographic  mapping  of  user  coordinates  onto  the  current  viewport 

void  swf_ortho  (double  xmin,  double  xmax,  double  ymin,  double  ymax,  double 
zmin,  double  zmax) 


The  swf_ortho()  funcion  defines  a  orthographic  mapping  of  user  coordinates  onto  the  current  viewport. 


swf_ortho2  (php  4  >=  400) 

Defines  2D  orthographic  mapping  of  user  coordinates  onto  the  current  viewport 

void  swf_ortho2  (double  xmin,  double  xmax,  double  ymin,  double  ymax) 


The  swf_ortho2()  function  defines  a  two  dimensional  orthographic  mapping  of  user  coordinates  onto  the 
current  viewport,  this  defaults  to  one  to  one  mapping  of  the  area  of  the  Flash  movie.  If  a  perspective 
transformation  is  desired,  the  swf_perspective  ()  function  can  be  used. 


swf_perspecti  ve  (php  4  >=  4.0.0) 

Define  a  perspective  projection  transformation 
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void  swf_perspective  (double  fovy,  double  aspect,  double  near,  double  far ) 


The  swf_perspective()  function  defines  a  perspective  projection  transformation.  The  fovy  parameter  is 
field-of-view  angle  in  the  y  direction.  The  aspect  parameter  should  be  set  to  the  aspect  ratio  of  the 
viewport  that  is  being  drawn  onto.  The  near  parameter  is  the  near  clipping  plane  and  the  far 
parameter  is  the  far  clipping  plane. 

Nota:  Various  distortion  artifacts  may  appear  when  performing  a  perspective  projection,  this  is 
because  Flash  players  only  have  a  two  dimensional  matrix.  Some  are  not  to  pretty. 


swfpolarview  (php  4  >=  4.0.0 


Define  the  viewer’s  position  with  polar  coordinates 


void  swf  polarview  (double  dist,  double  azimuth,  double  incidence,  double 
twist ) 


The  swf_polarview()  function  defines  the  viewer’s  position  in  polar  coordinates.  The  dist  parameter 
gives  the  distance  between  the  viewpoint  to  the  world  space  origin.  The  azimuth  parameter  defines  the 
azimuthal  angle  in  the  x,y  coordinate  plane,  measured  in  distance  from  the  y  axis.  The  incidence 
parameter  defines  the  angle  of  incidence  in  the  y,z  plane,  measured  in  distance  from  the  z  axis.  The 
incidence  angle  is  defined  as  the  angle  of  the  viewport  relative  to  the  z  axis.  Finally  the  twist  specifies 
the  amount  that  the  viewpoint  is  to  be  rotated  about  the  line  of  sight  using  the  right  hand  rule. 


swf  lookat  (PHP  4  >=  4.0.0) 


Define  a  viewing  transformation 


void  swf_lookat  (double  view_x,  double  view_y,  double  view_z,  double 
reference_x,  double  reference_y,  double  reference_z,  double  twist) 


The  swf_lookat()  function  defines  a  viewing  transformation  by  giving  the  viewing  position  (the 
parameters  view_x,  view_y ,  and  view_z)  and  the  coordinates  of  a  reference  point  in  the  scene,  the 
reference  point  is  defined  by  the  reference_x,  reference_y  ,  and  reference_z  parameters. 
The  twist  controls  the  rotation  along  with  viewer’s  z  axis. 
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swfpushmatrix  (php  4  >=  4.0.0 

Push  the  current  transformation  matrix  back  unto  the  stack 

void  swf_pushmatrix  () 


The  swf_pushmatrix()  function  pushes  the  current  transformation  matrix  back  onto  the  stack. 


swfpopmatrix  (php  4  >=  4.0.0 

Restore  a  previous  transformation  matrix 

void  swf_popmatrix  () 


The  swf_popmatrix()  function  pushes  the  current  transformation  matrix  back  onto  the  stack. 


swfscale  (PHP  4  >=  4.0.0) 

Scale  the  current  transformation 

void  swf_scale  (double  x,  double  y,  double  z) 


The  swf_scale()  scales  the  x  coordinate  of  the  curve  by  the  value  of  the  x  parameter,  the  y  coordinate  of 
the  curve  by  the  value  of  the  y  parameter,  and  the  z  coordinate  of  the  curve  by  the  value  of  the  z 
parameter. 


swftranslate  (php  4  >=  4  0  o> 

Translate  the  current  transformations 

void  swf_translate  (double  x,  double  y,  double  z) 


The  swf_translate()  function  translates  the  current  transformation  by  the  x,  y,  and  z  values  given. 
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swf  rotate  (PHP  4  >=  4.0.0) 


Rotate  the  current  transformation 


void  swf_rotate  (double  angle,  string  axis) 


The  swf_rotate()  rotates  the  current  transformation  by  the  angle  given  by  the  angle  parameter  around 
the  axis  given  by  the  axis  parameter.  Valid  values  for  the  axis  are  ’x’  (the  x  axis),  ’y’  (the  y  axis)  or  ’z’ 
(the  z  axis). 


swfposround  <php  4  >=  4  o  0) 

Enables  or  Disables  the  rounding  of  the  translation  when  objects  are  placed  or  moved 

void  swf  posround  (int  round) 


The  swf_posround()  function  enables  or  disables  the  rounding  of  the  translation  when  objects  are  placed 
or  moved,  there  are  times  when  text  becomes  more  readable  because  rounding  has  been  enabled.  The 
round  is  whether  to  enable  rounding  or  not,  if  set  to  the  value  of  1,  then  rounding  is  enabled,  if  set  to  0 
then  rounding  is  disabled. 
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Para  usar  las  funciones  SNMP  en  Unix  necesita  instalar  el  paquete  UCD  SNMP 

(http://ucd-snmp.ucdavis.edu/).  En  Windows  estas  funciones  estan  solamente  disponibles  en  NT  y  no  en 
Win95/98. 

Importante:  Para  usar  el  paquete  UCD  SNMP,  necesita  definir  NO_ZEROLENGTH_COMMUNITY  a  1 
antes  de  compilarlo.  Despues  de  configurar  UCD  SNMP,  edite  config.h  y  busque 
NO_ZEROLENGTH_COMMUNITY.  Descomente  la  lfnea  #define.  Deberia  de  verse  como  sigue: 

#def ine  NO_ZEROLENGTH_COMMUNITY  1 


Si  ve  faltas  de  segmentacion  desconocidas  en  combinacion  con  los  comandos  SNMP,  no  siga  las 
siguientes  instrucciones.  Si  no  desea  recompilar  UCD  SNMP,  puede  compilar  PHP  con  la  opcion 
— enable-ucd-snmp-hack  la  cual  trabajara  entorno  a  las  mismas  caracterfsticas. 
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Va  a  buscar  un  objeto  SNMP 


string  snmpget  (string  hostname,  string  community,  string  object_id  [,  int 
timeout  [,  int  retries]]) 


Devuelve  el  valor  de  un  objeto  SNMP  en  caso  de  exito  y  false  en  caso  de  error. 

La  funcion  snmpget()  es  usada  para  leer  el  valor  de  un  objeto  SNMP  especificado  por  el  object_id. 
El  agente  SNMP  es  especificado  por  el  hostname  y  la  comunidad  lectora  es  especificada  por  el 
parametro  community. 


Ssyscontact  =  snmpget("  127.0.0. 1",  "public",  "system.SysContact.O") 


snmpset  (PHP  3>=  3.0.12,  PHP  4  >=  4.0.0) 


Va  a  buscar  un  objeto  SNMP 


string  snmpget  (string  hostname ,  string  community ,  string  object_id,  string 
type,  mixed  value  [,  int  timeout  [,  int  retries]]) 


Establece  el  valor  especificado  para  el  objeto  SNMP,  devolviendo  true  en  caso  de  exito  o  false  en 
caso  de  error. 

La  funcion  snmpset()  es  usada  para  establecer  el  valor  de  un  objeto  SNMP  especificado  por  el 
object_id.  El  agente  SNMP  es  espcificado  por  el  hostname  y  la  comunidad  lectora  por  el 
parametro  community. 


snmpwalk  (PHP  3,  PHP  4  >=4.0.0) 


Busqueda  por  un  arbol  de  informacion  acerca  de  un  entidad  de  red 

array  snmpwalk  (string  hostname,  string  community,  string  object_id  [,  int 
timeout  [,  int  retries]]) 
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Devuelve  una  matriz  de  valores  de  objetos  SMNP  comenzando  por  el  object_id()  como  rafz  y  false  en 
caso  de  error. 

La  funcion  snmpwalk()  es  usada  para  leer  todos  los  valores  de  un  agente  SNMP  especificado  por  el 
hostname.  Community  especifica  la  comunidad  lectora  para  el  agente.  Un  object_id  nulo  se 
toma  como  la  rafz  del  arbol  de  los  objetos  SNMP  y  todos  los  objetos  por  debajo  de  ese  arbol  son 
devueltos  como  una  matriz.  Si  object_id  es  especificado,  todos  los  objetos  SNMP  por  debajo  de 
object_id  son  devueltos. 

$a  =  snmpwalk ("127 . 0.0.1",  "public", 


Encima  de  una  funcion  de  llamada  podrfan  devolverse  todos  los  objetos  SNMP  del  agente  SNMP  en 
ejecucion  en  el  servidor  local.  Uno  puede  pasar  por  todos  los  valores  con  un  bucle. 

for  ($i=0;  $i<count ( $a) ;  $i++)  { 

echo  $  a [ $ i ] ; 

} 


snmpwalkoid  (PHP  3>=  3.0.8,  PHP  4  >=  4.0.0) 


Busqueda  por  un  arbol  de  information  acerca  de  un  entidad  de  red 


array  snmpwalkoid  (string  hostname,  string  community,  string  object_id  [,  int 
timeout  [,  int  retries]]) 


Devuelve  una  matriz  asociativa  con  los  identificadores  de  los  objetos  y  sus  respectivos  valores 
comenzando  por  el  object_id  como  rafz  y  false  en  caso  de  error. 

La  funcion  snmpwalkoidf)  es  usada  para  leer  todos  los  identificadores  de  objetos  y  sus  respectivos 
valores  de  un  agente  SNMP  especificado  por  el  nombre  del  servidor.  La  lectura  de  community 
especifica  la  comunidad  para  el  agente.  Un  object_id  nulo  es  tornado  como  la  rafz  del  arbol  de 
objetos  SNMP  y  todos  los  objetos  por  debajo  de  este  arbol  son  devueltos  como  una  matriz.  Si 
object_id  es  especificado,  todos  los  objetos  SNMP  inferiores  al  object_id  son  devueltos. 

La  existencia  de  snmpwalkoidf)  y  snmpwalk^)  tiene  razones  historicas.  Ambas  funciones  son 
proporcionadas  para  compatibilidad  hacia  atras. 

$a  =  snmpwalkoid (" 127 . 0 . 0 . 1 "  ,  "public", 
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La  llamada  a  las  funciones  superiores  devuelve  todos  los  objetos  SNMP  del  agente  SNMP  en  ejecucion 
en  el  servidor  local.  Uno  puede  pasar  por  todos  los  valores  con  un  bucle. 

for  (reset  ($a) ;  $i  =  key($a);  next ($a) )  { 

echo  "$i:  $a [ $i ] <br>\n" ; 

} 


snmp_get_quick_print  (php  3>=  3.0.8,  php  4  >=  4 .0 ,0) 

Va  a  buscar  el  valor  actual  de  la  biblioteca  UCD  estableciendo  quick_print 

boolean  snmp_get_quick_print  (void  ) 

Delvuele  el  valor  actual  almacenado  en  la  biblioteca  UCD  para  quick_print.  quick_print  esta  desactivado 
por  defecto. 

$quickprint  =  snmp_get_quick_print ( ) ; 


La  llamada  a  la  funcion  superior  podria  devolver  false  si  quick_print  esta  activo,  y  true  si  quick_print 
esta  activo. 

snmp_get_quick_print()  esta  solamente  disponible  cuando  estemos  usando  la  biblioteca  UCD  SNMP. 
Esta  funcion  no  esta  disponible  cuando  estemos  usando  la  biblioteca  Windows  SNMP. 

Ver:  snmp_get_quick_print()  para  una  description  completa  de  lo  que  hace  quick_print. 


snmp_set_quick_print  (php  3>=  3 .0 .8,  php  4  >=  4.o.o) 

Establece  el  valor  de  quick_print  con  el  de  la  biblioteca  UCD  SNMP. 

void  snmp  set  quick  print  (boolean  quick_print) 


Establece  el  valor  de  quick_print  con  la  biblioteca  UCD  SNMP.  Cuando  esto  esta  establecido  (1),  la 
biblioteca  SNMP  devolvera  valores  ’quick  printed’.  De  esta  manera  solo  el  valor  sera  impreso.  Cuando 
quick_print  no  esta  activada  (por  defecto)  la  biblioteca  UCD  SNMP  imprime  information  extra 
incluyendo  el  tipo  del  valor  (p.  Ej.  IPAddress  o  OID).  Adicionalmente,  si  quick_print  no  esta  activado,  la 
biblioteca  imprime  valores  hexadecimales  adicionales  para  todas  las  cadenas  de  3  o  menos  caracteres. 
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El  ajuste  de  quick_print  es  generalmente  usado  cuando  usando  la  information  devuelta  con  anterioridad 
se  muestra. 

snmp_set_quick_print (0)  ; 

$a  =  snmpget ("127.0.0.1",  "public",  1.3. 6. 1.2. 1.2.2. 1.9.1" ); 

echo  "$a<BR>\n"; 

snmp  set  quick  print  (1) ; 

$a  =  snmpget ("127.0.0.1",  "public",  ". 1.3. 6. 1.2. 1.2.2. 1.9.1" ); 
echo  "$a<BR>\n"; 


El  primer  valor  impreso  debe  de  ser:  ’Timeticks:  (0)  0:00:00.00’,  donde  qick_print  se  activa,  solo  se 
imprimira  ’0:00:00.00’. 

Por  defecto  la  biblioteca  UCD  SNMP  devuelve  valores  detallados,  quick_print  es  usado  para  devolver 
solamente  el  valor. 

Las  cadenas  son  mantenidas  normalmente  con  comillas  extra,  esto  sera  corregido  en  versiones 
posteriores. 

snmp_get_quick_print ')  esta  solo  disponible  cuando  estemos  usando  la  biblioteca  UCD  SNMP.  Esta 
funcion  no  esta  disponible  cuando  estemos  usando  la  biblioteca  Windows  SNMP. 
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Aviso 

This  module  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  these 
functions,  these  function  names,  in  concreto  ANYTHING  documented  here  can 
change  in  a  future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this 
module  at  your  own  risk. 


The  socket  extension  implements  a  low-level  interface  to  the  socket  communication  functions,  providing 
the  possibility  to  act  as  a  socket  server  as  well  as  a  client. 

For  a  more  generic  client-side  socket  interface,  see  fsockopen ')  and  pfsockopen '). 

When  using  the  socket  functions  described  here,  it  is  important  to  remember  that  while  many  of  them 
have  identical  names  to  their  C  counterparts,  they  often  have  different  declarations.  Please  be  sure  to  read 
the  descriptions  to  avoid  confusion. 

That  said,  those  unfamiliar  with  socket  programming  can  still  find  a  lot  of  useful  material  in  the 
appropriate  Unix  man  pages,  and  there  is  a  great  deal  of  tutorial  information  on  socket  programming  in  C 
on  the  web,  much  of  which  can  be  applied,  with  slight  modifications,  to  socket  programming  in  PHP. 


Ejemplo  1.  Socket  example:  Simple  TCP/IP  server 

This  example  shows  a  simple  talkback  server.  Change  the  address  and  port  variables  to  suit  your  setup 
and  execute.  You  may  then  connect  to  the  server  with  a  command  similar  to:  telnet  192.168.1.53  10000 
(where  the  address  and  port  match  your  setup).  Anything  you  type  will  then  be  output  on  the  server  side, 
and  echoed  back  to  you.  To  disconnect,  enter  ’quit’. 

<?php 

error_reporting (E_ALL) ; 

/*  Allow  the  script  to  hang  around  waiting  for  connections.  */ 
set_time_limit (0) ; 

$address  =  '192.168.1.53'; 

$port  =  10000; 

if  ( ($SOCk  =  socket (AF_INET,  SOCK_STREAM,  0))  <  0)  { 

echo  "socket  ()  failed:  reason:  "  .  strerror  ( $sock)  .  "\n"; 

} 

if  ( ($ret  =  bind($sock,  $address,  $port) )  <  0)  { 

echo  "bind()  failed:  reason:  "  .  strerror  ( $ret )  .  "\n"; 

} 

if  ( ($ret  =  listen ( $sock,  5))  <  0)  { 

echo  "listen  ()  failed:  reason:  "  .  strerror  ( $ret )  .  "\n"; 

} 

do  { 

if  (($msgsock  =  accept_connect ($sock) )  <  0)  { 
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echo  "accept_connect ( )  failed:  reason:  "  .  strerror ( $msgsock)  .  "\n"; 

break; 


do  { 

$buf  = 

$ret  =  read ($msgsock,  $buf,  2048); 
if  ($ret  <  0)  { 

echo  "read()  failed:  reason:  "  .  strerror  ($ret)  .  "\n"; 
break  2; 

} 

if  ($ret  ==  0)  { 

break  2; 

} 

$buf  =  trim($buf); 
if  ( $buf  ==  ' quit' )  { 

close ($msgsock) ; 
break  2; 

} 

$talkback  =  "PHP:  You  said  ' $buf ' . \n"; 

write ( $msgsock,  $talkback,  strlen ( $talkback) ) ; 

echo  "$buf\n"; 

}  while  (true) ; 
close ($msgsock) ; 

}  while  (true) ; 

close ( $sock) ; 

?> 


Ejemplo  2.  Socket  example:  Simple  TCP/IP  client 

This  example  shows  a  simple,  one-shot  HTTP  client.  It  simply  connects  to  a  page,  submits  a  HEAD 
request,  echoes  the  reply,  and  exits. 

<?php 

error_reporting (E_ALL) ; 

echo  "<h2>TCP/IP  Connection</h2>\n" ; 

/*  Get  the  port  for  the  WWW  service.  */ 

$service_port  =  get servby name (' www' ,  'tcp'); 

/*  Get  the  IP  address  for  the  target  host.  */ 

$address  =  gethostbyname ( ' www . php . net ' ) ; 

/*  Create  a  TCP/IP  socket.  */ 

$socket  =  socket (AF_INET,  SOCK_STREAM,  0); 
if  ($socket  <  0)  { 

echo  "socket!)  failed:  reason:  "  .  strerror ( $socket )  .  "\n"; 

}  else  { 

"socket!)  successful:  "  .  strerror ($socket)  .  "\n"; 
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} 

echo  "Attempting  to  connect  to  '$address'  on  port  ' $service  port' 

$result  =  connect  ($socket,  Saddress,  $service_port) ; 
if  ($result  <  0)  { 

echo  "connect  ()  failed . \nReason :  ($result)  "  .  strerror  ( $result )  .  "\n"; 

}  else  { 

echo  "OK.\n"; 

} 

$in  =  "HEAD  /  HTTP/1 . 0\r\n\r\n" ; 

$out  =  "; 

echo  "Sending  HTTP  HEAD  request..."; 
write ( $socket,  $in,  strlen ($in) ) ; 
echo  "OK.\n"; 

echo  "Reading  response : \n\n" ; 
while  (read ($socket,  $out,  2048))  { 

echo  $out; 

} 

echo  "Closing  socket..."; 
close  ($socket) ; 
echo  "OK.\n\n"; 

?> 
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accept_connect  (4.0.2  -  4.0.6  only) 

Accepts  a  connection  on  a  socket. 

int  accept_connect  (int  socket) 


After  the  socket  socket  has  been  created  using  socket)),  bound  to  a  name  with  bind)),  and  told  to  listen 
for  connections  with  listen  )),  this  function  will  accept  incoming  connections  on  that  socket.  Once  a 
successful  connection  is  made,  a  new  socket  descriptor  is  returned,  which  may  be  used  for 
communication.  If  there  are  multiple  connections  queued  on  the  socket,  the  first  will  be  used.  If  there  are 
no  pending  connections,  accept_connect()  will  block  until  a  connection  becomes  present.  If  socket 
has  been  made  non-blocking  using  socket_set_blocking()  or  set_nonblock(),  an  error  code  will  be 
returned. 

The  socket  descriptor  returned  by  accept_connect()  may  not  be  used  to  accept  new  connections.  The 
original  listening  socket  socket,  however,  remains  open  and  may  be  reused. 

Returns  a  new  socket  descriptor  on  success,  or  a  negative  error  code  on  failure.  This  code  may  be  passed 
to  strerror))  to  get  a  textual  explanation  of  the  error. 

See  also  bind  ),  connect)),  listen)),  socket)),  and  strerror)). 


bind  (4.0.2  -  4.0.6  only) 

Binds  a  name  to  a  socket. 


int  bind  (int  socket,  string  address  [,  int  protocol ]) 


bind()  binds  the  name  given  in  address  to  the  socket  described  by  socket,  which  must  be  a  valid 
socket  descriptor  created  with  socket  )). 

The  address  parameter  is  either  an  IP  address  in  dotted-quad  notation  (e.g.  127 . 0 . 0 . 1),  if  the  socket 
is  of  the  af_inet  family;  or  the  pathname  of  a  Unix-domain  socket,  if  the  socket  family  is  af_unix. 

The  port  parameter  is  only  used  when  connecting  to  an  af_inet  socket,  and  designates  the  port  on  the 
remote  host  to  which  a  connection  should  be  made. 

Returns  zero  on  success,  or  a  negative  error  code  on  failure.  This  code  may  be  passed  to  strerror  ))  to  get  a 
textual  explanation  of  the  error. 

See  also  accept_connect)),  connect)),  listen  ),  socket)),  and  strerror)). 


1034 


Sockets 

connect  (4.0.2 -4.0.6  only) 

Initiates  a  connection  on  a  socket. 


int  connect  (int  socket,  string  address  [,  int  port]) 


Initiates  a  connection  using  the  socket  descriptor  socket,  which  must  be  a  valid  socket  descriptor 
created  with  socket)). 

The  address  parameter  is  either  an  IP  address  in  dotted-quad  notation  (e.g.  127 . 0 . 0 . 1),  if  the  socket 
is  of  the  af_inet  family;  or  the  pathname  of  a  Unix-domain  socket,  if  the  socket  family  is  af_unix. 

The  port  parameter  is  only  used  when  connecting  to  an  af_inet  socket,  and  designates  the  port  on  the 
remote  host  to  which  a  connection  should  be  made. 

Returns  zero  on  success,  or  a  negative  error  code  on  failure.  This  code  may  be  passed  to  strerror;)  to  get  a 
textual  explanation  of  the  error. 

See  also  bindO,  listen;),  socket;),  and  strerror')). 


listen  (4.0.2  -  4.0.6  only) 

Listens  for  a  connection  on  a  socket. 

int  listen  (int  socket,  int  backlog ) 

After  the  socket  socket  has  been  created  using  socket;)  and  bound  to  a  name  with  bind;),  it  may  be 
told  to  listen  for  incoming  connections  on  socket.  A  maximum  of  backlog  incoming  connections 
will  be  queued  for  processing. 

listen()  is  applicable  only  to  sockets  with  type  SOCK_STREAM  or  S0CK_SEQPACKET. 

Returns  zero  on  success,  or  a  negative  error  code  on  failure.  This  code  may  be  passed  to  strerror;)  to  get  a 
textual  explanation  of  the  error. 

See  also  accept_connect;),  bind;),  connect  ),  socket)),  and  strerror)). 

socket  (4.0.2  -  4.0.6  only) 

Create  a  socket  (endpoint  for  communication). 

int  socket  (int  domain,  int  type,  int  protocol) 
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Creates  a  communication  endpoint  (a  socket),  and  returns  a  descriptor  to  the  socket. 

The  domain  parameter  sets  the  domain.  Currently,  af_inet  and  af_unix  are  understood. 

The  type  parameter  selects  the  socket  type.  This  is  one  of  SOCK_STREAM,  SOCK_dgram, 
SOCK_SEQPACKET,  SOCK_RAW,  SOCK_RDM,  or  SOCK_PACKET. 

protocol  sets  the  protocol. 

Returns  a  valid  socket  descriptor  on  success,  or  a  negative  error  code  on  failure.  This  code  may  be  passed 
to  strerror[)  to  get  a  textual  explanation  of  the  error. 

For  more  information  on  the  usage  of  socket)),  as  well  as  on  the  meanings  of  the  various  parameters,  see 
the  Unix  man  page  socket  (2). 

See  also  accept_connectO,  bind  '),  connect  3,  listen)),  and  strerror). 


strerror  (4.0.2  -  4.0.6  only) 

Return  a  string  describing  a  socket  error. 

string  strerror  (int  errno) 


strerror()  takes  as  its  errno  parameter  the  return  value  of  one  of  the  socket  functions,  and  returns  the 
corresponding  explanatory  text.  This  makes  it  a  bit  more  pleasant  to  figure  out  why  something  didn’t 
work;  for  instance,  instead  of  having  to  track  down  a  system  include  file  to  find  out  what  ’-111’  means, 
you  just  pass  it  to  strerror)),  and  it  tells  you  what  happened. 


Ejemplo  1.  strerror))  example 


<?php 

if  ( ($socket  =  socket (AF_INET,  SOCK_STREAM,  0))  <  0)  { 

echo  "socket))  failed:  reason:  "  .  strerror  ($socket)  .  "\n"; 

} 

if  (  ($ret  =  bind ($socket,  '127.0.0.1',  80))  <  0)  { 

echo  "bind))  failed:  reason:  "  .  strerror  ( $ret )  .  "\n"; 

} 

?> 

The  expected  output  from  the  above  example  (assuming  the  script  is  not  run  with  root  privileges): 

bind))  failed:  reason:  Permission  denied 
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See  also  accept_connect'),  bind  ),  connect^),  listen  ),  and  socket^). 
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LXXXIII.  Funciones  de  cadenas 


Todas  estas  funciones  manipulan  cadenas  de  varias  maneras.  En  las  secciones  sobre  expresiones 
regulares  y  manejo  de  URL  se  pueden  encontrar  secciones  mas  especializadas. 
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AddCSIashes  (PHP  4  >=  4.0.0) 

Marca  una  cadena  con  barras  al  estilo  del  C 

string  addcslashes  (string  cad,  string  listcar) 


Devuelve  una  cadena  con  barras  invertidas  antes  de  los  caracteres  listados  en  el  parametro  listcar. 
Tambien  marca  \n,  \r  etc.  Al  estilo  del  C,  los  caracteres  con  codico  ASCII  inferior  a  32  y  superior  a  126 
son  convertidos  a  representacion  octal.  Tenga  cuidado  cuando  marque  caracteres  alfanumericos.  Puede 
especificar  un  rango  en  listcar  como  el  "\0..\37",  que  marcana  todos  los  caracteres  con  codigo  ASCII 
entre  0  y  3 1 . 

Ejemplo  1.  Ejemplo  de  addcslashes() 

$tradformado  =  addcslashes  ($no_transf,  " \0 . . \37 ! @\177 . . \377 " ) ; 


Nota:  Anadida  en  PHP4b3-dev. 


Vea  tambien  stripe  slashes)),  stripslashes )),  htmlspecialchars)),  htmlspecialchars '),  y  quotemeta)). 


AddSlashes  (PHP  3,  PHP  4  >=4.0.0) 


Marca  una  cadena  con  barras 


string  addslashes  (string  cad) 


Devuelve  una  cadena  con  barras  invertidas  frente  a  los  caracteres  que  necesitan  marcarse  en  consultas  de 
bases  de  datos,  etc.  Estos  son  la  comilla  simple  (' ),  comilla  doble  ("),  barra  invertida  (\)  y  NUL  (el  byte 
nulo). 

Vea  tambien  stripslashes)),  htmlspecialchars)),  y  quotemeta)). 


bin2hex  (PHP  3>=  3.0.9,  PHP  4  >=  4.0.0) 


Convierte  datos  binarios  en  su  representacion  hexadecimal 
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string  bin2hex  (string  cad) 


Devuelve  una  cadena  ASCII  que  contiene  la  representation  hexadecimal  de  cad.  La  conversion  se 
realiza  byte  a  byte,  con  los  4  bits  superiores  primero. 


chop  (PHP  3,  PHP  4  >=  4.0.0) 

Elimina  espacios  sobrantes  al  final 

string  chop  (string  cad) 

Devuelve  la  cadena  argumento  sin  los  espacios  sobrantes,  incluyendo  los  saltos  de  llnea. 
Ejemplo  1.  Ejemplo  de  chop() 

$recortada  =  chop  ($linea); 

Vea  tambien  trim,). 

chr  (PHP  3,  PHP  4  >=4.0.0) 

Devuelve  un  caracter  especlfico 

string  chr  (int  ascii) 

Devuelve  una  cadena  de  un  caracter  que  congiene  el  caracter  especificado  por  ascii. 

Ejemplo  1.  Ejemplo  de  chr() 

$cad  .=  chr  (27);  /*  anade  un  caracter  de  escape  al  final  de  $cad  */ 
/*  A  veces  esto  es  mas  util  */ 

$cad  =  sprintf  ("La  cadena  termina  en  escape:  %c",  27); 

Esta  funcion  complementa  a  old  ).  Vea  tambien  sprintf))  con  una  cadena  de  formato  %c. 
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chunk_split  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 

Divide  una  cadena  en  trozos  mas  pequenos 

string  chunk_split  (string  cadena  [,  int  tamatrozo  [,  string  final]]) 

Se  puede  utilizar  para  trocear  una  cadena  en  pedazos  mas  pequenos,  lo  que  es  util,  p.ej.,  para  convertir  la 
salida  de  la  funcion  base64_encode  a  la  semantica  del  RFC  2045.  Inserta  la  cadena  final  cada 
tamatrozo  (por  defecto  vale  76)  caracteres.  Devuelve  la  nueva  cadena  y  deja  intacta  la  original. 

Ejemplo  1.  Ejemplo  de  chunk_split() 

#  formatear  $datos  usando  la  semantica  del  RFC  2045 
$nueva_cad  =  chunk_split  (base64_encode ($datos) ) ; 

Esta  funcion  es  notablemente  mas  rapida  que  ereg_replace '). 

Nota:  Esta  funcion  se  anadio  en  la  3.0.6. 


convert_cyr_string  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 

Convierte  de  un  juego  de  caracteres  Cirflico  a  otro 

string  convert_cyr_string  (string  cad,  string  desde,  string  hasta ) 


Esta  funcion  convierte  la  cadena  dada  de  un  juego  de  caracteres  Cirflico  a  otro.  Los  argumentos  desde 
y  hasta  son  caracteres  sencillos  que  representan  los  juegos  de  caracteres  Cirflicos  fuente  y  destino.  Los 
tipos  soportados  son: 

•  k  -  koi8-r 

•  w  -  windows- 1251 

•  i  -  iso8859-5 

•  a  -  x-cp866 

•  d  -  x-cp866 

•  m  -  x-mac-cyrillic 
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count_chars  (php  4  >=  4.0.0 

Devuelve  informacion  sobre  los  caracteres  usados  en  una  cadena 


mixed  count_chars  (string  cadena,  [modo]) 


Cuenta  el  numero  de  apariciones  de  cada  valor  de  byte  (0..255)  en  cadena  y  lo  devuelve  de  varias 
maneras.  El  parametro  opcional  modo  vale  por  defecto  0.  Dependiendo  de  modo,  count_chars()  puede 
devolver: 

•  0  -  una  matriz  con  el  valor  del  byte  como  clave  y  la  frecuencia  de  cada  uno  como  valor. 

•  1  -  como  el  0,  pero  listando  unicamente  los  valores  de  byte  con  frecuencia  superior  a  cero. 

•  2  -  como  el  0,  pero  listando  unicamente  los  valores  de  byte  con  frecuencia  igual  a  0. 

•  3  -  se  devuelve  una  cadena  que  contiene  todos  los  valores  de  byte  utilizados. 

•  4  -  se  devuelve  una  cadena  que  contiene  todos  los  valores  de  byte  no  utilizados. 

Nota:  Esta  funcion  se  anadio  en  el  PHP  4.0. 


crc32  (php  4) 

Calcula  el  polinomio  crc32  de  una  cadena 

int  crc32  (string  cad) 

Genera  el  polinomio  de  comprobacion  de  reduncancia  cfclica  de  32  bits  de  cad.  Se  suele  utilizar  para 
validad  la  integridad  de  los  datos  transmitidos. 

Vea  tambien:  md5  [) 

crypt  (PHP  3,  PHP  4  >=  4.0.0) 

Encripta  una  cadena  mediante  DES 

string  crypt  (string  cad  [,  string  semilla] ) 
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crypt()  encriptara  una  cadena  utilizando  el  metodo  estandar  de  encriptacion  del  Unix  DES.  Los 
argumentos  son  una  cadena  a  encriptar  y  una  cadena  semilla  de  2  caracteres  en  la  que  basar  la 
encriptacion.  Vea  la  pagina  de  manual  de  Unix  sobre  crypt  para  mas  informacion. 

Si  el  argumento  de  semilla  no  se  proporciona,  sera  generado  aleatoriamente  por  el  PHP. 

Algunos  sistemas  operativos  soportan  mas  de  un  tipo  de  encriptacion.  De  hecho,  algunas  veces  la 
encriptacion  estandar  DES  es  sustitufda  por  un  algoritmo  de  encriptacion  basado  en  MD5.  El  tipo  de 
encriptacion  es  disparado  por  el  argumento  semilla.  En  tiempo  de  instalacion,  el  PHP  determina  la 
capacidad  de  la  funcion  de  encriptacion  y  aceptara  semillas  para  otros  tipos  de  encriptacion.  Si  no  se 
proporciona  la  semilla,  el  PHP  intentara  generar  una  semilla  estandar  DES  de  2  caraceres  por  defecto, 
excepto  si  el  tipo  de  encriptacion  estandar  del  sistema  es  el  MD5,  en  cuyo  caso  se  generara  una  semilla 
aleatoria  compatible  con  MD5.  El  PHP  fija  una  constante  llamada  CRYPT_SALT_LENGTH  que  le 
especifica  si  su  sistema  soporta  una  semilla  de  2  caracteres  o  si  se  debe  usar  la  semilla  de  12  caracteres 
del  NDS. 

La  funcion  estandar  de  encriptacion  crypt()  contiene  la  semilla  como  los  dos  primeros  caracteres  de  la 
salida. 

En  los  sistemas  en  los  que  la  funcion  crypt()  soporta  multiples  tipos  de  encriptacion,  las  siguienes 
constantes  son  fijadas  a  0  6  1  dependiendo  de  si  esta  disponible  el  tipo  dado: 

•  CRYPT_STD_DES  -  Encriptacion  DES  estandar  con  semilla  de  2  caracteres 

•  CRYPT_EXT_DES  -  Encriptacion  DES  extendida  con  semilla  de  9  caracteres 

•  CRYPT_MD5  -  Encriptacion  MD5  con  semilla  de  12  caracteres  y  comenzando  por  $1$ 

•  CRYPT_BLOWFISH  -  Encriptacion  DES  extendida  con  semilla  de  16  caracteres  y  comenzando  por 

$2$ 

No  hay  funcion  de  desencriptado  porque  crypt()  utiliza  un  algoritmo  de  una  sola  via. 

Vea  tambien:  md5'). 


echo 


(unknown) 

Da  salida  a  una  o  mas  cadenas 

echo  (string  argl,  string 


[argn] . . .) 


Da  salida  a  todos  sus  parametros. 

echo()  no  es  realmente  una  funcion  (es  una  sentencia  del  lenguaje)  de  modo  que  no  se  requiere  el  uso  de 
los  parentesis. 

Ejemplo  1.  Ejemplo  de  echo() 

echo  "Hola  Mundo"; 
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echo  "Esto  se  extiende 

por  varias  lineas.  Los  saltos  de  linea 
tambien  se  envian"; 

echo  "Esto  se  extiende\npor  varias  lineas.  Los  saltos  de  lineaXntambien  se  envian" 


Nota:  De  hecho,  si  desea  pasar  mas  de  un  parametro  a  echo  no  debe  encerrarlos  entre  parentesis. 


Vea  tambien:  print'),  printf '),  y  flush  '). 


explode  (PHP  3,  PHP  4  >=  4.0.0) 


Divide  una  cadena  por  otra 


array  explode  (string  separador,  string  cadena  [,  int  limite]) 


Devuelve  una  matriz  de  cadenas,  cada  una  de  las  cuales  es  una  subcadena  de  cadena  formada  mediante 
su  division  en  las  fronteras  marcadas  por  la  cadena  separador.  Si  se  especifica  limite,  la  matriz 
devuelta  contendra  un  maximo  de  limite  elementos  con  el  ultimo  conteniendo  el  resto  de  la  cadena. 


Ejemplo  1.  Ejemplo  de  explode!) 

$pizza  =  "trozol  trozo2  trozo3  trozo4  trozo5  trozo6"; 
$trozos  =  explode  ("  ",  $pizza) ; 


Vea  tambien  split  3  e  implode '). 


get_html_translation_table  (php  4  >=  4.o.0) 


Devuelve  la  tabla  de  traduccion  utilizada  por  htmlspecialcharsO  y  htmlcntities ') 


string  get_html_translation_table  (int  tabla ) 
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get_html_translation_table()  devolvera  la  tabla  de  traduccion  que  se  usa  internamente  para 
htmlspecialchars ')  y  htmlentities)).  Hay  dos  nuevas  definiciones  ( HTML_ENTITIES , 
HTML_SPECIALCHARS )  que  le  permiten  especificar  la  tabla  deseada. 

Ejemplo  1.  Ejemplo  de  Tabla  de  Traduccion 

$trad  =  get_html_translation_table  (HTML_ENTITIES) ; 

$cad  =  "Hallo  &  <Frau>  &  Kramer"; 

$codif  =  strtr  ($cad,  $trad) ; 


La  variable  $codif  contendra  ahora:  "Hallo  &amp;  &lt;Frau&gt;  &amp;  Kr&auml;mer". 
Lo  interesante  es  usar  la  funcion  arrayjip ')  para  cambiar  la  direction  de  la  traduccion. 

$trad  =  array_flip  ($trad) ; 

$original  =  strtr  ($cad,  $trad) ; 

El  contenido  de  $original  seria:  "Hallo  &  <Frau>  &  Kramer". 


Nota:  Esta  funcion  fue  anadida  en  PHP  4.0. 


Vea  tambien:  htmlspecialchars '),  htmlentities'),  strtr'),  y  array_flip)). 


get_meta_tags  (PHP  3>=  3.0.4,  PHP  4  >=  4.0.0) 

Extrae  todas  las  etiquetas  meta  de  un  archivo  y  retorna  una  matriz 

array  get_meta_tags  (string  nombrefich  [,  int  use_ruta_include] ) 


Abre  el  nombrefi  ch  y  lo  trocea  lmea  a  lmea  buscando  etiquetas  <meta>  de  la  forma 
Ejemplo  1.  Ejemplo  de  Etiquetas  Meta 

<meta  name="autor"  content="nombre"> 

<meta  name="etiquetas"  content="documentacion  de  php3"> 

</head>  <! —  el  proceso  se  detiene  aqui  — > 


(preste  atencion  a  los  finales  de  lmea  -  el  PHP  utiliza  una  funcion  nativa  para  trocear  la  entrada,  de  modo 
que  un  archivo  de  Mac  no  funcionara  en  Unix). 

El  valor  de  la  propiedad  name  queda  como  clave  y  el  valor  de  la  propiedad  content  queda  como  el  valor 
de  la  matriz  devuelta,  de  modo  que  pueda  usar  facilmente  funciones  estandar  de  matrices  para  recorrerla 
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o  para  acceder  a  valores  individuales.  Los  caracteres  especiales  en  el  valor  de  name  son  sustitufdos  por 
y  el  resto  es  convertido  a  minusculas. 

Fijando  use_ruta_include  a  1  hara  que  el  PHP  intente  abrir  el  archivo  a  traves  de  la  ruta  de 
inclusion. 


hebrev  (PHP  3,  PHP  4  >=  4.0.0) 

Convierte  Hebreo  logico  a  texto  visual 

string  hebrev  (string  texto_hebreo  [,  int  max_cars_por_linea] ) 

El  parametro  opcional  max_cars_por_linea  indica  el  maximo  numero  de  caracteres  que  se 
emitiran  por  li'nea.  La  funcion  intenta  evitar  cortar  palabras. 

Vea  tambien  hebrevc  )) 

hebrevc  (PHP  3,  PHP  4  >=  4.0.0) 

Convierte  Hebreo  logico  a  texto  visual  con  conversion  de  saltos  de  lfnea 

string  hebrevc  (string  texto_hebreo  [,  int  max  cars  por  linea 1 ) 

Esta  funcion  es  similar  a  hebrev  ))  con  la  diferencia  que  convierte  las  nuevas  lfneas  (\n)  a  "<br>\n".  El 
parametro  opcional  max_cars_por_linea  indica  el  maximo  numero  de  caracteres  que  se  emitiran 
por  lfnea.  La  funcion  intenta  evitar  cortar  palabras. 

Vea  tambien  hebrev  )) 


htmlentities  (PHP  3,  PHP  4  >=4.0.0) 

Convierte  todos  los  caracteres  aplicables  a  entidades  HTML 

string  htmlentities  (string  cadena ) 

Esta  funcion  es  del  todo  identica  a  htmlspecialchars )),  excepto  que  traduce  todos  los  caracteres  que 
tienen  equivalente  como  entidad  HTML. 
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Actualmente  se  utiliza  el  juego  de  caracteres  ISO-8859- 1. 

Vea  tambien  htmlspecialchars))  y  nl2br)). 


htmlspecialchars  (php 3,  php 4 >=  4 .0 ,0) 

Convierte  caracteres  especiales  a  entidades  HTML 

string  htmlspecialchars  (string  cadena) 


Ciertos  caracteres  tienen  significados  especiales  en  HTML,  y  deben  ser  representados  por  entidades 
HTML  si  se  desea  preservar  su  significado.  Esta  funcion  devuelve  una  cadena  con  dichas  conversiones 
realizadas. 

Esta  funcion  es  util  para  evitar  que  el  texo  entrado  por  el  usuario  contenga  marcas  HTML,  como  ocurre 
en  aplicaciones  de  foros  o  libros  de  visita. 

Actualmente,  las  traducciones  hechas  son: 

•  ’&’  (ampersand)  se  convierte  en  ’&amp;’ 

•  (doble  comilla)  se  convierte  en  ’&quot;’ 

•  ’<’  (menor  que)  se  convierte  en  ’&lt;’ 

•  ’>’  (mayor  que)  se  convierte  en  ’&gt;’ 


Notese  que  esta  funcion  no  traduce  nada  mas  que  lo  mostrado  mas  arriba.  Para  una  traduccion  de 
entidades  completa,  vea  htmlentities)). 

Vea  tambien  htmlentities))  y  n!2br'). 


implode  (PHP  3,  PHP  4  >=  4.0.0) 

Unir  elementos  de  una  matriz  mediante  una  cadena 

string  implode  (string  cola,  array  piezas ) 

Devuelve  una  cadena  que  contiene  una  representation  de  todos  los  elementos  de  la  matriz  en  el  mismo 
orden,  pero  con  la  cadena  cola  en  medio  de  los  mismos. 
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Ejemplo  1.  Ejemplo  de  implode() 

$separada_dospuntos  =  implode  $matrizay) ; 


Vea  tambien  explode;),  join  '),  y  split;). 

join  (PHP  3,  PHP  4  >=  4.0.0) 

Une  elementos  de  una  tabla  mediante  una  cadena 

string  join  (string  cola,  array  plezas ) 

join()  es  un  alias  para  implode;),  y  es  identica  en  todo. 

Vea  tambien  explode'),  implode'),  y  split'). 

levenshtein  (PHP  3>=  3.0.17,  PHP  4) 

Calcula  la  distancia  Levenshtein  entre  dos  cadenas 

int  levenshtein  (string  cadi,  string  cad2) 

Esta  funcion  devuelve  la  distancia  Levenshtein  entre  las  dos  cadenas  argumento,  6  -1  si  alguna  de  las 
cadenas  tiene  mas  de  255  caracteres. 

La  distancia  Levenshtein  se  define  como  el  mini  mo  numero  de  caracteres  que  se  tienen  que  sustituir, 
insertar  o  borrar  para  transformar  cadi  en  cad2.  La  complejidad  del  algoritmo  es  0  (m*n) ,  donde  n  y  m 
son  las  longitudes  de  cadi  y  cad2  (bastante  bueno  si  se  la  compara  con  similar_text;),  que  es 
0(max(n,m)**3),  pero  aun  es  cara). 

Vea  tambien  soundex;),  similar_text')  y  metaphone (). 

Itrim  (PHP  3,  PHP  4  >=  4.0.0) 

Elimina  el  espacio  en  bianco  del  principio  de  una  cadena 

string  Itrim  (string  cad) 
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Esta  funcion  elimina  el  espacio  en  bianco  del  principio  de  una  cadena  y  devuelve  la  cadena  resultante. 
Los  caracteres  de  espacio  que  elimina  realmente  son:  "\n",  "\r",  "\t",  "\v",  "\0",  y  el  espacio  en  si. 

Vea  tambien  chop/)  y  trim'). 


md5 


(PHP3,  PHP  4  >=  4.0.0) 


Calcula  el  hash  md5  de  una  cadena 


string  md5  (string  cad) 


Calcula  el  hash  (extracto)  MD5  de  cad  usaneo  el  Algoritmo  de  Resumen  de  Mensajes  MD5  de  RSA 
Data  Security,  Inc.  (http://www.faqs.org/rfcs/rfcl321.html). 

Vea  tambien:  crc32/) 


metaphone  (php  4  >=4oo) 


Calcula  la  clave  "metafona"  de  una  cadena 


string  metaphone  (string  cad) 


Calcula  la  clave  "metafona"  de  cad. 

Similarmente  a  soundex/),  metaphone  crea  la  misma  clave  para  palabras  que  suenan  parecidas.  Es  mas 
precisa  que  la  funcion  soundex/),  pues  conoce  las  reglas  basicas  de  la  pronunciation  del  Ingles.  Las 
claves  metafonicas  generadas  son  de  longitud  variable. 

Metaphone  fue  desarrollado  por  Lawrence  Philips  <lphilips@ verity.com>.  Se  describe  en  ["Practical 
Algorithms  for  Programmers",  Binstock  &  Rex,  Addison  Wesley,  1995], 

Nota:  Esta  funcion  se  anadio  en  PHP  4.0. 


nl2br  (PHP  3,  PHP  4  >=  4.0.0) 


Convierte  nuevas  llneas  a  saltos  de  lrnea  HTML 
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string  nl2br  (string  cadena) 

Devuelve  la  cadena  con  ’<BR>’  insertados  antes  de  cada  nueva  llnea. 

Vea  tambien  htmlspecialcharsO,  htmlentities ')  y  wordwrap '). 

ord  (PHP  3,  PHP  4  >=  4.0.0) 

Devuelve  el  valor  ASCII  de  un  caracter 

int  ord  (string  cadena) 

Devuelve  el  valor  ASCII  del  primer  caracter  de  cadena.  Esta  funcion  complementa  a  chr'). 
Ejemplo  1.  Ejemplo  de  ord() 

if  (ord  ($cad)  ==  10)  { 

echo  "El  primer  caracter  de  \$cad  es  un  salto  de  linea.\n"; 

} 


Vea  tambien  chr  ). 


parse_str  (PHP  3,  PHP  4  >=4.0.0) 


Divide  la  cadena  en  variables 


void  parse_str  (string  cad) 


Divide  cad  como  si  fuera  la  cadena  de  consulta  enviada  por  un  URL  y  crea  las  variables  en  el  ambito 
actual. 

Ejemplo  1.  Usando  parse_str() 

$cad  =  "primero=valor&segundo [ ] =esto+funciona&segundo [ ] =otro"  ; 
parse_str ($cad) ; 

echo  $primero;  /*  escribe  "valor"  */ 

echo  $segundo[0];  /*  escribe  "esto  funciona"  */ 

echo  $segundo[l];  /*  escribe  "otro"  */ 
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print  (unknown) 

Emite  una  cadena 

print  (string  arg) 

Emite  arg. 

Vea  tambien:  echo)),  printf)),  y  flush)). 

printf  (PHP  3,  PHP  4  >=  4.0.0) 

Emite  una  cadena  con  formato 

int  printf  (string  formato  [,  mixed  args...]) 

Produce  una  salida  segun  el  formato ,  que  es  descrito  en  la  documentation  para  sprintf)). 

Vea  tambien:  print)),  sprintf)),  sscanf'),  fscanf(),  y  flush)). 

quoted_printable_decode  (php  3>=  3.0.6,  php  4  >=  4  0  o> 

Convierte  una  cadena  con  marcacion  imprimible  a  una  cadena  de  8  bits 

string  quoted_printable_decode  (string  cad) 

Esta  funcion  devuelve  una  cadena  binaria  de  8  bit  que  se  corresponde  con  la  cadena  con  marcacion 
imprimible  decodificada.  Esta  funcion  es  similar  a  imap_qprint)),  pero  sin  requerir  que  el  modulo  IMAP 
funcione. 
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quotemeta  (PHP3,  PHP  4  >=  4.0.0) 

Quote  meta  characters 

string  quotemeta  (string  cad) 

Devuelve  una  version  de  la  cadena  con  una  barra  invertida  (\)  antes  de  cada  caracter  de  este  conjunto: 

.  \\  +  *  ?  [  A  ]  (  $  ) 

Vea  tambien  addslashes)),  htmlentities)),  htmlspecialchars '),  nl2br'),  y  stripslashes'). 

rtrim  (PHP  3,  PHP  4  >=4.0.0) 

Elimina  espacios  en  bianco  al  final  de  la  cadena. 

string  rtrim  (string  cad) 

Devuelve  la  cadena  argumento  sin  espacios  en  bianco  ni  saltos  de  linea  al  final.  Es  un  alias  para  chop))- 
Ejemplo  1.  Ejemplo  de  rtrim() 

$recortada  =  rtrim  ($linea) ; 

Vea  tambien  trim)),  ltrim)). 

sscanf  (PHP  4) 

Trocea  la  entrada  desde  una  cadena  segun  un  formato  dado 

mixed  sscanf  (string  cad,  string  formato  [,  string  varl...]) 

La  funcionsscanfO  es  la  funcion  de  entrada  analoga  de  printf).  sscanf()  lee  del  parametro  de  cadena 
cad  y  lo  interpreta  segun  el  formato  especificado.  Si  solo  se  pasan  dos  parametros  a  esta  funcion,  los 
valores  devueltos  se  haran  en  una  matriz. 
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Ejemplo  1.  Ejemplo  de  sscanf() 

/ /  obteniendo  el  numero  de  serie 
$numserie  =  sscanf ( "SN/2350001 " , " SN/%d" ) ; 

//  y  la  fecha  de  fabricacion 
$fecha  =  "01  Enero  2000"; 

list ($dia,  $mes,  $anno)  =  sscanf ( $fecha,  " %d  %s  %d"); 

echo  "El  objeto  $numserie  fue  fabricado  el:  $anno-" . substr ($mes, 0, 3) . "-$dia\n" 


Si  se  pasan  los  parametros  opcionales,  la  funcion  devolvera  el  numero  de  valores  asignados.  Los 
parametros  opcionales  deben  ser  pasados  por  referencia. 


Ejemplo  2.  Ejemplo  de  sscanf()  -  usando  parametros  opcionales 

/ /  obtener  autor  y  generar  la  ficha  DocBook 
$autor  =  "24\tLewis  Carroll"; 

$n  =  sscanf ($autor, "%d\t%s  %s",  &$id,  &$nombre,  &$apell) ; 
echo  "<autor  id='$id'> 

<f irstname>$nombre</ f irstname> 
<surname>$apell</surname> 

</author>\n" ; 


Vea  tambien:  fscanfQ,  printf'),  y  sprintf'). 


setlocale  (PHP  3,  PHP  4  >=  4.0.0) 

Fija  la  informacion  de  localidad 

string  setlocale  (string  categoria,  string  localidad) 


categoria  es  una  cadena  que  especifica  la  categoria  de  las  funciones  afectadas  por  el  ajuste  de 
localidad: 

•  LC_ALL  para  todas  las  funciones 

•  LC_COLLATE  para  la  comparacion  de  cadenas  -  aun  no  inclufda  en  el  PHP 

•  LC_CTYPE  para  la  conversion  y  clasificacion  de  caracteres,  como  por  ejemplo  strtoupper') 

•  LC_MONETARY  para  localeconvl)  -  aun  no  inclufda  en  el  PHP 

•  LC_NUMERIC  para  el  separador  decimal 

•  LC_TIME  para  el  formato  de  fecha  y  hora  con  strftime  3 
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Si  localidad  es  la  cadena  vacfa  " ",  los  nombres  de  localidad  se  fijaran  a  partir  de  las  variables  de 
entorno  con  los  mismos  nombres  de  las  categories  anteriores,  o  desde  "LANG". 

Si  la  localidad  es  cero  o  "0",  el  ajuste  de  localidad  no  se  ve  afectado  y  solo  se  devuelve  el  ajuste  actual. 

setlocale  devuelve  la  nueva  localidad,  o  false  si  la  funcionalidad  de  localization  no  esta  disponible  en 
la  plataforma,  la  localidad  especificada  no  existe  o  el  nombre  de  categorfa  no  es  valido.  Un  nombre  de 
categorfa  no  valido  tambien  produce  un  mensaje  de  aviso. 


similartext  (PHP  3>=  3.0.7,  PHP  4  >=  4.0.0) 


Calcula  la  similitud  entre  dos  cadenas 


int  similar_text  (string  primera,  string  segunda 


double  porcentaje ] ) 


Esta  funcion  calcula  la  similitud  entre  dos  cadenas  segun  se  describe  en  Oliver  [1993].  Notese  que  esta 
implementation  no  utiliza  una  pila  como  en  el  pseudo-codigo  de  Oliver,  sino  llamadas  recursivas  que 
pueden  o  no  acelerar  el  proceso  completo.  Notese  tambien  que  la  complejidad  de  este  algoritmo  es 
0(N**3),  donde  N  es  la  longitud  de  la  cadena  mas  larga. 

Pasando  una  referencia  como  tercer  argumento,  similar_text()  calculara  para  usted  la  similitud  como 
porcentaje.  Devuelve  el  numero  de  caracteres  coincidentes  en  ambas  cadenas. 


soundex  (PHP  3,  PHP  4  >=4.0.0) 

Calcula  la  clave  soundex  de  una  cadena 


string  soundex  (string  cad) 


Calcula  la  clave  soundex  de  cad. 

Las  claves  soundex  tienen  la  propiedad  de  que  las  palabras  que  se  pronuncian  de  forma  parecida  tienen  la 
misma  clave,  de  modo  que  se  pueden  usar  para  simplificar  la  busqueda  en  las  bases  de  datos  cuando  se 
conoce  la  pronunciation  pero  no  la  transcription.  Esta  funcion  soundex  devuelve  una  cadena  de  4 
caracteres  que  comienza  por  una  letra. 

Esta  funcion  soundex  en  particular  es  la  descrita  por  Donald  Knuth  en  "The  Art  Of  Computer 
Programming,  vol.  3:  Sorting  And  Searching",  Addison- Wesley  (1973),  pp.  391-392. 


Ejemplo  1.  Ejemplos  de  Soundex 

soundex  ("Euler")  ==  soundex  ("Ellery")  ==  'E460'; 
soundex  ("Gauss")  ==  soundex  ("Ghosh")  ==  'G200'; 
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soundex  ("Knuth")  ==  soundex  ("Kant")  ==  'H416'; 
soundex  ("Lloyd")  ==  soundex  ("Ladd")  ==  'L300'; 
soundex  ("Lukasiewicz")  ==  soundex  ( "Lissa jous " )  ==  'L222'; 


sprintf  (PHP  3,  PHP  4  >=  4.0.0) 


Devuelve  una  cadena  con  formato 


string  sprintf  (string  formato  [,  mixed  args...]) 


Devuelve  una  cadena  producida  de  acuerdo  a  la  cadena  de  formato. 

La  cadena  de  formato  esta  compuesta  por  cero  o  mas  directivas:  caracteres  ordinarios  (excepto  %)  que 
son  copiados  directamente  al  resultado,  y  especificaciones  de  conversion,  cada  una  de  las  cuales  provoca 
la  obtencion  de  su  propio  parametro.  Esto  se  aplica  tanto  a  sprintf()  como  a  printf '). 

Cada  especificacion  de  conversion  consiste  en  uno  de  estos  elementos,  por  orden: 

1.  Un  especificador  de  relleno  opcional  que  indica  que  caracter  se  utilizara  para  rellenar  el  resultado 
hasta  el  tamano  de  cadena  correcto.  Este  puede  ser  un  espacio  o  un  0  (caracter  cero).  El  valor  por 
defecto  es  rellenar  con  espacios.  Un  caracter  de  relleno  alternativo  se  puede  especificar  prefijandolo 
con  una  comilla  simple  (' ).  Vea  los  ejemplos  mas  abajo. 

2.  Un  especificador  de  alineacion  opcional  que  indica  si  el  resultado  debe  ser  alineado  a  la  izquierda  o 
a  la  derecha.  Por  defecto  se  alinea  a  la  derecha;  un  caracter  -  aquf  lo  justificara  a  la  izquierda. 

3.  Un  numero  opcional,  un  especificador  de  ancho  que  dice  el  numero  de  caracteres  (minimo)  en  que 
deberfa  resultar  esta  conversion. 

4.  Un  especificador  de  precision  opcional  que  indica  cuantos  dfgitos  decimales  deben  mostrarse  para 
los  numeros  en  coma  flotante.  Esta  option  no  tienen  efecto  para  otros  tipos  que  no  sean  double. 

(Otra  funcion  util  para  formatear  numeros  es  number_format')). 

5.  Un  especificador  de  tipo  que  indica  el  tipo  a  usar  para  tratar  los  datos  de  los  argumentos.  Los  tipos 
posibles  son: 

%  -  un  caracter  literal  de  porcentaje.  No  se  precisa  argumento. 

b  -  el  argumento  es  tratado  como  un  entero  y  presentado  como  un  numero  binario. 

c  -  el  argumento  es  tratado  como  un  entero,  y  presentado  como  el  caracter  con  dicho  valor  ASCII. 

d  -  el  argumento  es  tratado  como  un  entero  y  presentado  como  un  numero  decimal. 

f  -  el  argumento  es  tratado  como  un  doble  y  presentado  como  un  numero  de  coma  flotante. 

o  -  el  argumento  es  tratado  como  un  entero,  y  presentado  como  un  numero  octal. 

s  -  el  argumento  es  tratado  como  una  cadena  y  es  presentado  como  tal. 

x  -  el  argumento  es  tratado  como  un  entero  y  presentado  como  un  numero  hexadecimal  (con  minusculas). 
x  -  el  argumento  es  tratado  como  un  entero  y  presentado  como  un  numero  hexadecimal  (con  mayusculas). 
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Vea  tambien:  printf'),  sscanf'),  fscanf(),  y  number_formatO- 


Ejemplo  1.  Ejemplo  de  sprintf():  enteros  rellenos  con  ceros 

$fechaiso  =  sprintf  ( "%04d-%02d-%02d" ,  $anno,  $mes,  $dia) ; 


Ejemplo  2.  Ejemplo  de  sprintf():  formateando  monedas 

$pelasl  =  68.75; 

$pelas2  =  54 . 35; 

$pelas  =  $pelasl  +  $pelas2; 

//  echo  $pelas  mostrara  "123.1"; 

$formateado  =  sprintf  ("%01.2f",  $pelas); 

//  echo  $formateado  mostrara  "123.10" 


strcasecmp  (PHP  3>=  3.0.2,  PHP  4  >=  4.0.0) 

Comparacion  de  cadenas  insensible  a  mayusculas  y  minusculas  y  segura  en  modo  binario 

int  strcasecmp  (string  cadi,  string  cad2) 


Devuelve  <  0  si  cadi  es  menor  que  cad2\  >  0  si  cadi  es  mayor  que  cad2,  y  0  si  son  iguales. 

Ejemplo  1.  Ejemplo  de  strcasecmpO 

$varl  =  "Hello"; 

$var2  =  "hello"; 

if  ((strcasecmp  ($varl,  $var2))  { 

echo  ' $varl  es  igual  a  $var2  en  una  comparacion  sin  tener  en  cuenta  ' 
.'mayusculas  o  minusculas'; 


Vea  tambien  ereg(),  strcmp)),  substr(),  stristr)),  y  strstr'). 
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strchr  (PHP  3,  PHP  4  >=  4.0.0) 

Encuentra  la  primera  aparicion  de  un  caracter 

string  strchr  (string  pajar,  string  aguja) 

Esta  funcion  es  un  alias  para  strstr)),  y  es  identica  en  todo. 

strcmp  (PHP  3,  PHP  4  >=4.0.0) 

Comparacion  de  cadenas  con  seguridad  binaria 

int  strcmp  (string  cadi,  string  cad2) 

Devuelve  <  0  si  cadi  es  menor  que  cad2\  >  0  si  cadi  es  mayor  que  cad2,  y  0  si  son  iguales. 

Notese  que  esta  comparacion  es  sensible  a  mayusculas  y  minusculas. 

Vea  tambien  ereg'),  strcasecmpO,  substr(),  stristr"),  strncmpO,  y  strstr'). 

strcspn  (PHP  3>=  3.0.3,  PHP  4  >=  4.0.0) 

Encuentra  la  longitud  del  elemento  inicial  que  no  coincide  con  la  mascara 

int  strcspn  (string  cadi,  string  cad2) 

Devuelve  la  longitud  del  segmento  inicial  de  cadi  que  no  contiene  ninguno  de  los  caracteres  de  cad2. 
Vea  tambien  strspn '). 

strip_tags  (PHP  3>=  3.0.8,  PHP  4  >=  4.0.0) 

Elimina  marcas  HTML  y  PHP  de  una  cadena 

string  strip_tags  (string  cad  [,  string  etiq_permitidas] ) 
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Esta  funcion  intenta  eliminar  todas  las  etiquetas  HTML  y  PHP  de  la  cadena  dada.  Causa  error  por 
precaucion  en  caso  de  etiquetas  incompletas  o  falsas.  Utiliza  la  misma  maquina  de  estados  para  eliminar 
las  etiquetas  que  la  funcion  fgetss '). 

Puede  usar  el  parametro  opcional  para  especificar  las  etiquetas  que  no  deben  eliminarse. 

Nota:  etiq_permitidas  fue  anadido  en  PHP  3.0.13,  PHP4B3. 


stripcslashes  <php  4  >=  4 .0 ,0) 

Desmarca  la  cadena  marcada  con  addcslashes ') 

string  stripcslashes  (string  cad) 

Devuelve  una  cadena  con  las  barras  invertidas  eliminadas.  Reconoce  las  marcas  tipo  C  \n,  \r  ...,  y  la 
representation  octal  y  hexadecimal. 

Nota:  Anadida  en  PHP4b3-dev. 

Vea  tambien  addcslashes))- 

stripslashes  (PHP  3,  PHP  4>=  4.0.0) 

Desmarca  la  cadena  marcada  con  addslashes ') 

string  stripslashes  (string  cad) 

Devuelve  una  cadena  con  las  barras  invertidas  eliminadas  (V  se  convierte  en  ' ,  etc.).  Las  barras 
invertidas  dobles  se  convierten  en  sencillas. 

Vea  tambien  addslashes))- 
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stristr  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 

strstrf)  sin  tener  en  cuenta  mayusculas  o  minusculas 

string  stristr  (string  pajar,  string  aguja) 

Devuelve  todo  el  pajar  desde  la  primera  aparicion  de  la  aguja,  siendo  el  pajar  examinado  sin  tener 
en  cuenta  mayusculas  o  minusculas. 

Si  la  aguja  no  se  encuentra,  devuelve  false. 

Si  la  aguja  no  es  una  cadena,  es  convertida  a  entero  y  usada  como  codigo  de  un  caracter  ASCII. 

Vea  tambien  strchr),  strrchr)),  substr'),  y  ereg)). 

strlen  (PHP  3,  PHP  4  >=  4.0.0) 

Obtiene  la  longitud  de  la  cadena 

int  strlen  (string  cad) 

Devuelve  la  longitud  de  la  cadena. 


strnatcmp  (PHP  4  >=  4.0.0) 

Compara  cadenas  usando  un  algoritmo  de  "orden  natural" 

int  strnatcmp  (string  cadi,  string  cad2) 


Esta  funcion  implementa  un  algoritmo  de  comparacion  que  ordena  las  cadenas  alfanumericas  como  lo 
harfa  un  ser  humano,  que  es  lo  que  se  denomina  "orden  natural".  A  continuation  se  puede  ver  un  ejemplo 
de  la  diferencia  entre  este  algoritmo  y  los  algoritmos  de  ordenacion  de  cadenas  habituales  en  los 
ordenadores  (utilizados  en  strcmpQ): 

$matrizl  =  $matriz2  =  array  ( " imgl2 . png" , " imglO . png" , " img2 . png" , " imgl . png" ) ; 
echo  "Comparacion  de  cadenas  estandar\n"; 
usort ($matrizl, "strcmp") ; 
print_r ( $matrizl ) ; 

echo  " \nComparacion  de  cadenas  en  orden  natural\n"; 
usort ($matriz2, "strnatcmp") ; 
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print_r ( $matriz2 ) ; 


El  codigo  anterior  generara  la  siguiente  salida: 


Comparacion  de  cadenas  estandar 
Array 
( 


0] 

=  > 

imgl . png 

1] 

=  > 

imglO . png 

2] 

=  > 

imgl2 . png 

3] 

=  > 

img2 . png 

Comparacion  de  cadenas  en  orden  natural 
Array 
( 


0] 

=  > 

imgl . png 

1] 

=  > 

img2 . png 

2] 

=  > 

imglO .png 

3] 

=  > 

imgl2 . png 

Para  mas  informacion,  vea  la  pagina  de  Martin  Pool  sobre  Comparacion  de  Cadenas  en  Orden  Natural 
(http://www.linuxcare.com.au/projects/natsort/). 

De  forma  similar  a  otras  funciones  de  comparacion  de  cadenas,  esta  devuelve  <  0  si  cadi  es  menor  que 
cad2;  >  0  si  cadi  es  mayor  que  cad2 ,  y  0  si  son  iguales. 

Notese  que  esta  comparacion  es  sensible  a  mayusculas  y  minusculas. 

Vea  tambien  ereg/),  strcasecmp/),  substrO,  stristr'),  strcmp'),  strncmp/),  strnatcasecmp'),  y  strstr'). 


strnatcasecmp  (PHP  4  >=  4.0.0) 

Comparacion  de  cadenas  insensible  a  mayusculas  y  minusculas  usando  un  algoritmo  de  "orden  natural" 

int  strnatcasecmp  (string  cadi,  string  cad2) 


Esta  funcion  implementa  un  algoritmo  de  comparacion  que  ordena  las  cadenas  alfanumericas  como  lo 
harfa  un  ser  humano.  El  comportamiento  de  esta  funcion  es  similar  a  strnatcmp '),  pero  la  comparacion 
no  es  sensible  a  mayusculas  y  minusculas.  Para  mas  informacion,  vea  la  pagina  de  Martin  Pool  sobre 
Comparacion  de  Cadenas  en  Orden  Natural  (http://www.linuxcare.com.au/projects/natsort/). 

De  forma  similar  a  otras  funciones  de  comparacion  de  cadenas,  esta  devuelve  <  0  si  cadi  es  menor  que 
cad2\  >  0  si  cadi  es  mayor  que  cad2,  y  0  si  son  iguales. 

Vea  tambien  ereg'),  strcasecmp'),  substr'),  stristrO,  strcmp'),  strncmp'),  strnatcmp'),  y  strstr (). 
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strncmp  (PHP  4  >=  4.0.0) 

Comparacion  de  los  n  primeros  caracteres  de  cadenas,  con  seguridad  binaria 

int  strncmp  (string  cadi,  string  cad2,  int  largo ) 

Esta  funcion  es  similar  a  strcmpQ,  con  la  diferencia  que  se  puede  especificar  el  (lfmite  superior  del) 
numero  de  caractares  (largo)  de  cada  cadena  que  se  usaran  en  la  comparacion.  Si  alguna  de  las  cadenas 
es  menor  que  el  largo,  se  usara  su  longitud  para  la  comparacion. 

Devuelve  <  0  si  cadi  es  menor  que  cad2\  >  0  si  cadi  es  mayor  que  cad2,  y  0  si  son  iguales. 

Notese  que  esta  comparacion  es  sensible  a  mayusculas  y  minusculas. 

Vea  tambien  ereg'),  strcasecmp'),  substr)),  stristr)),  strcmp)),  y  strstr)). 


str_pad  (php  4) 

Rellena  una  cadena  con  otra  hasta  una  longitud  dada 

string  str  pad  (string  entrada,  int  tama_relleno  [,  string  cad_relleno  [,  int 
tipo_relleno] ] ) 


Esta  funcion  rellena  la  cadena  entrada  por  la  derecha,  la  izquierda  o  por  ambos  lados  hasta  el  largo 
indicado.  Si  no  se  especifica  el  argumento  opcional  cad_relleno,  entrada  es  rellenada  con 
espacios.  En  caso  contrario,  sera  rellenada  con  los  caracteres  de  cad_relleno  hasta  el  lfmite. 

El  argumento  opcional  tipo_relleno  puede  valer  STR_PAD_RIGHT,  STR_PAD_LEFT,  o 
STR_PAD_BOTH.  Si  no  se  especifica,  se  asume  que  vale  STR_PAD_RIGHT. 

Si  el  valor  de  tama_relleno  es  negativo  o  menor  que  la  longitud  de  la  cadena  de  entrada,  no  se 
produce  rellenado  alguno. 


Ejemplo  1.  Ejemplo  de  str_pad() 


$entrada  =  "Alien"; 
print  str_pad ( $entrada,  10) 
print  str_pad ( $entrada,  10, 
print  str_pad ( $entrada,  10, 


STR_PAD_LEFT ) ; 
STR_PAD_BOTH ) ; 


//  produce  "Alien  " 
//  produce  "-=-=-Alien" 
//  produce  " _ Alien _ " 
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strpos  (PHP  3,  PHP  4  >=  4.0.0) 

Encuentra  la  position  de  la  primera  aparicion  de  una  cadena 

int  strpos  (string  pajar,  string  aguja  [,  int  desplazamiento] ) 


Devuelve  la  position  numerica  de  la  primera  aparicion  de  la  aguja  en  la  cadena  pajar.  A  diferencia 
de  strrposO,  esta  funcion  puede  tomar  una  cadena  completa  como  aguja  y  se  utilizara  en  su  totalidad. 

Si  la  aguja  no  es  hayada,  devuelve  false. 

Nota:  Es  facil  confundir  los  valores  de  retorno  para  "caracter  encontrado  en  la  position  0"  y 
"caracter  no  encontrado".  Aqui  se  indica  como  detectar  la  diferencia: 

//  en  PHP  4 . 0b3  y  posteriores: 

$pos  =  strpos  ($micadena,  "b"); 

if  ($pos  ===  false)  {  //  nota:  tres  signos  igual 
//  no  encontrado  . . . 

} 


//  en  versiones  anteriores  a  la  4 . 0b3 : 
$pos  =  strpos  ($micadena,  "b"); 
if  (is_string  ($pos)  &&  !$pos)  { 

//no  encontrado  . . . 

} 


Si  la  aguja  no  es  una  cadena,  se  convierte  a  entero  y  se  aplica  como  el  valor  ordinal  de  un  caracter. 

El  parametro  optional  desplazamiento  le  permite  especificar  a  partir  de  que  caracter  del  pajar 
comenzar  a  buscar.  La  position  devuelta  es  aun  relativa  al  comienzo  de  pajar. 

Vea  tambien  strrpos'),  strrchr'),  substrQ,  stristr'),  y  strstr'). 


strrchr  (PHP  3,  PHP  4  >=  4.0.0) 

Encuentra  la  ultima  aparicion  de  un  caracter  en  una  cadena 

string  strrchr  (string  pajar,  string  aguja ) 


Esta  funcion  devuelve  la  portion  del  pajar  que  comienza  en  la  ultima  aparicion  de  la  aguja  y 
continua  hasta  el  final  del  pajar. 
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Devuelve  false  si  la  aguja  no  es  hallada. 

Si  la  aguja  contiene  mas  de  un  caracter,  solo  se  usara  el  primero. 

Si  la  aguja  no  es  una  cadena,  se  convierte  a  entero  y  se  aplica  como  el  valor  ordinal  de  un  caracter. 

Ejemplo  1.  Ejemplo  de  strrchr() 

/ /  obtener  el  ultimo  directorio  de  $PATH 
$dir  =  substr  (strrchr  ( $PATH,  1); 

/ /  obtener  todo  tras  el  ultimo  salto  de  llnea 
$texto  =  "Line  l\nLine  2\nLine  3"; 

$apell  =  substr  (strrchr  ($texto,  10) ,  1  ) ; 


Vea  tambien  substr)),  stristr'),  y  strstr'). 


str_repeat  (PHP  4  >=  4.0.0) 

Repite  una  cadena 

string  str_repeat  (string  cad_entrada,  int  veces ) 

Devuelve  la  cad_entrada  repetida  veces.  veces  debe  ser  mayor  que  0. 

Ejemplo  1.  Ejemplo  de  str_repeat() 

echo  str_repeat  ("-=",  10); 

Esto  mostrara 

Nota:  Esta  funcion  fue  anadida  en  el  PHP  4.0. 


strrev  (PHP  3,  PHP  4  >=  4.0.0) 


Invierte  una  cadena 


string  strrev  (string  cadena) 
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Devuele  la  cadena  invertida. 

strrpos  (PHP  3,  PHP  4  >=  4.0.0) 

Encuentra  la  position  de  la  ultima  aparicion  de  un  caracter  en  una  cadena 

int  strrpos  (string  pajar,  char  aguja) 

Devuele  la  position  numerica  de  la  ultima  aparicion  de  la  aguja  en  el  pajar.  Notese  que  la  aguja  en 
este  caso  solo  puede  ser  un  caracter  unico.  Si  se  pasa  una  cadena  como  aguja,  solo  se  utilizara  el  primer 
caracter  de  la  misma. 

Si  la  aguja  no  es  hayada,  devuelve  false. 

Si  la  aguja  no  es  una  cadena,  se  convierte  a  entero  y  se  aplica  como  el  valor  ordinal  de  un  caracter. 
Vea  tambien  strpos '),  strrchr'),  substr)),  stristr'),  y  strstrj). 

strspn  (PHP  3>=  3.0.3,  PHP  4  >=  4.0.0) 

Encuentra  la  longitud  del  segmento  initial  que  coincide  con  la  mascara 

int  strspn  (string  cadi,  string  cad2) 

Devuelve  la  longitud  del  segmento  initial  de  cadi  que  consiste  por  entero  en  caracteres  contenidos  en 

cad2. 

strspn  ("42  es  la  respuesta.  £.Cual  es  la  pregunta  "1234567890"); 

devolvera  2  como  resultado. 

Vea  tambien  strcspnQ. 
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strstr  (PHP  3,  PHP  4  >=  4.0.0) 

Encuentra  la  primera  aparicion  de  una  cadena 

string  strstr  (string  pajar,  string  aguja) 

Devuelve  todo  el  pajar  desde  la  primera  aparicion  de  la  aguja  hasta  el  final. 

Si  la  aguja  no  es  hayada,  devuelve  false. 

Si  la  aguja  no  es  una  cadena,  se  convierte  a  entero  y  se  aplica  como  el  valor  ordinal  de  un  caracter. 

Nota:  Notese  que  esta  funcion  es  sensible  a  mayusculas  y  minusculas.  Para  busquedas  no 
sensibles,  utilice  stristr[). 


Ejemplo  1.  Ejemplo  de  strstr() 

$email  =  'sterling@designmultimedia.com'; 
$dominio  =  strstr  ($email,  '  @ '  )  ; 

print  $dominio;  //  imprime  Sdesignmultimedia . com 


Vea  tambien  stristrQ,  strrchr'),  subsfi\),  y  ereg)). 


strtok  (PHP  3,  PHP  4  >=4.0.0) 

Divide  una  cadena  en  elementos 


string  strtok  (string  argl,  string  arg2) 


strtok()  se  usa  para  dividir  en  elementos  una  cadena.  Es  decir,  que  si  tiene  una  cadena  como  "Esta  es  una 
cadena  de  ejemplo"  podrfa  dividirla  en  palabras  individuales  utilizando  el  espacio  como  divisor. 

Ejemplo  1.  Ejemplo  de  strtokO 

$cadena  =  "Esta  es  una  cadena  de  ejemplo"; 

$tok  =  strtok  ($cadena, "  "); 
while  ($tok)  { 

echo  "Palabra=$tok<br>" ; 
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$tok  =  strtok  ("  "); 

} 


Notese  que  solo  la  primera  llamada  a  strtok  utiliza  el  argumento  cadena.  Cada  llamada  subsiguiente 
necesita  solo  el  divisor  a  utilizar,  puesto  que  ella  guarda  la  position  actual  en  la  cadena.  Para  comenzar 
de  nuevo  o  para  dividir  otra  cadena,  simplemente  llame  a  strtok  con  el  argumento  de  cadena  y  se 
inicializara.  Notese  que  puede  poner  divisores  multiples  como  parametro.  La  cadena  sera  dividida 
cuando  alguno  de  los  caracteres  del  argumento  sea  hallado. 

Ademas  tenga  cuidado  si  sus  divisores  valen  "0",  pues  evalua  como  false  en  las  expresiones 
condicionales. 

Vea  tambien  split  )  y  explode'). 


strtolower  (PHP  3,  PHP  4  >=  4.0.0) 


Pasa  a  minusculas  una  cadena 


string  strtolower  (string  cad) 


Devuelve  la  cadena  con  todas  sus  letras  en  minusculas. 

Notese  que  las  letras  son  definidad  por  el  locale  actual.  Esto  quiere  decir  que,  por  ejemplo,  en  el  locale 
por  defecto  ("C"),  los  caracteres  como  la  N  no  seran  convertidos. 

Ejemplo  1.  Ejemplo  de  strtolower() 

$cad  =  "Maria  Tenia  Un  Corderito  al  que  QUERIA  Mucho"; 

$cad  =  strtolower ( $cad) ; 

print  $cad;  #  Visualiza  maria  tenia  un  corderito  al  que  querla  mucho 


Vea  tambien  strtoupper')  y  ucfirst)). 


strtoupper  (PHP  3,  PHP  4  >=  4.0.0) 

Pasa  a  mayusculas  una  cadena 

string  strtoupper  (string  cadena) 


Devuelve  la  cadena  con  todas  sus  letras  en  mayusculas. 
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Notese  que  las  letras  son  definidad  por  el  locale  actual.  Esto  quiere  decir  que,  por  ejemplo,  en  el  locale 
por  defecto  ("C"),  los  caracteres  como  la  n  no  seran  convertidos. 

Ejemplo  1.  Ejemplo  de  strtoupper() 

$cad  =  "Maria  Tenia  Un  Corderito  al  que  QUERfA  Mucho"; 

$cad  =  strtoupper  ($cad); 

print  $cad;  #  Visuaiza  MARiA  TENiA  UN  CORDERITO  AL  QUE  QUERfA  MUCHO 


Vea  tambien  strtolower)  and  ucfirst '). 


str_replace  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 

Sustitiye  todas  las  apariciones  de  la  aguja  en  el  pajar  por  la  cadena 

string  str_replace  (string  aguja,  string  cad,  string  pajar ) 


Esta  funcion  sustituye  todas  las  apariciones  de  la  aguja  en  el  pajar  por  la  cad  dada.  Si  no  precisa 
reglas  especiales  de  sustitucion,  debera  usar  siempre  esta  funcion  en  lugar  de  ereg_replace '). 

Ejemplo  1.  Ejemplo  de  str_replace() 

$bodytag  =  str_replace  ("%cuerpo%",  "negro",  "<body  text=%cuerpo%>" ) ; 


Esta  funcion  tiene  seguridad  binaria. 

Nota:  str_replace()  fue  anadida  en  PHP  3.0.6,  pero  tuvo  errores  hasta  el  PHP  3.0.8. 


Vea  tambien  ereg_replace ')  y  strtr'). 


strtr  (PHP  3,  PHP  4  >=4.0.0) 

Traduce  ciertos  caracteres 


string  strtr  (string  cad,  string  desde,  string  hasta) 
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Esta  funcion  trabaja  sobre  cad,  traduciendo  todas  las  apariciones  de  cada  caracter  en  desde  por  el 
caracter  correspondiente  cn  hast  a  y  devolviendo  el  resultado. 

Si  desde  y  hasta  son  de  distinta  longitud,  los  caracteres  extra  en  la  mas  larga  son  ignorados. 

Ejemplo  1.  Ejemplo  de  strtr() 

$addr  =  strtr($addr,  "aao",  "aao"); 


strtr()  puede  llamarso  solo  con  dos  argumentos.  Si  se  llama  de  esta  manera,  se  comporta  de  otro  modo: 
desde  debe  ser  entonces  una  matriz  que  contenga  pares  cadena  ->  cadena  que  seran  sustitufdos  en  la 
cadena  fuente.  strtr()  siempre  buscara  la  coincidencia  mas  larga  primero  y  *NO*  intentara  sustituir  nada 
en  lo  que  haya  trabajado  ya. 

Ejemplos: 

$trad  =  array  ("hola"  =>  "hey",  "hey"  =>  "hola"); 
echo  strtr("hey  a  todos,  dije  hola",  $trad)  .  "\n"; 


Mostrara:  "hola  a  todos,  dije  hey", 

Nota:  Esta  caracteristica  (2  argumentos)  fue  anadida  en  el  PHP  4.0 


Vea  tambien  ereg_replace '). 


substr  (PHP  3,  PHP  4  >=  4.0.0) 


Devuelve  parte  de  una  cadena 


string  substr  (string  cadena,  int  comienzo  [,  int  largo]) 


substr  devuelve  la  portion  de  cadena  especificada  por  los  parametros  comienzo  y  largo. 
Si  comienzo  es  positivo,  la  cadena  devuelta  comenzara  en  dicho  caracter  de  cadena. 
Ejemplos: 

$resto  =  substr  ("abcdef",  1);  //  devuelve  "bcdef" 

$resto  =  substr  ("abcdef",  1,  3);  //  devuelve  "bed" 


Si  comienzo  es  negativo,  la  cadena  devuelta  comenzara  en  dicha  posicion  desde  el  final  de  cadena. 
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Ejemplos: 


$resto  = 

substr 

( "abcdef" , 

-i) ; 

// 

devuelve 

M  £  || 

$resto  = 

substr 

( "abcdef" , 

-2)  ; 

// 

devuelve 

"ef  " 

$resto  = 

substr 

( "abcdef" , 

-3,  1); 

;  // 

devuelve 

"d" 

Si  se  especifica  largo  y  es  positivo,  la  cadena  devuelta  terminara  largo  caracteres  tras  el  comienzo. 
Si  esto  resulta  en  una  cadena  con  longitud  negativa  (porque  el  comienzo  esta  pasado  el  final  de  la 
cadena),  la  cadena  devuelta  contendra  unicamente  el  caracter  que  haya  en  comienzo. 

Si  se  especifica  largo  y  es  negativo,  la  cadena  devuelta  terminara  a  largo  caracteres  desde  el  final  de 
cadena.  Si  esto  resulta  en  una  cadena  con  longitud  negativa,  la  cadena  devuelta  contendra  unicamente 
el  caracter  que  haya  en  comienzo. 

Examples: 

$resto  =  substr  ("abcdef",  1,  -1);  //  devuelve  "bcde" 


Vea  tambien  strrchr')  y  ereg"). 

substr_count  (php  4  >=  4.o.0) 

Cuenta  el  numero  de  apariciones  de  la  subcadena 

int  substr_count  (string  pa  jar,  string  aguja ) 

substr_count()  devuelve  el  numero  de  veces  que  la  subcadena  aguja  se  encuentra  en  la  cadena  pa  jar. 

Ejemplo  1.  Ejemplo  de  substr_count() 

print  substr_count ( "This  is  a  test",  "is");  //  prints  out  2 


substr_replace  php 4 >=  4 .0 ,c» 


Sustituye  texto  en  una  parte  de  una  cadena 
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string  substr_replace  (string  cadena,  string  sustituto,  int  comienzo  [,  int 
largo] ) 


substr_replace()  sustituye  la  parte  de  cadena  delimitada  por  los  parametros  comienzo  y 
(opcionalmente)  largo  por  la  cadena  dada  en  sustituto.  Se  devuelve  el  resultado. 

Si  comienzo  es  positivo,  la  sustitucion  comenzara  en  dicha  posicion  dentro  de  la  cadena. 

Si  comienzo  es  negativo,  la  sustitucion  comenzara  en  dicha  posicion  pero  contando  desde  el  final  de 

cadena. 

Si  se  especifica  el  largo  y  es  positivo,  representa  el  largo  de  la  porcion  de  cadena  a  sustituir.  Si  es 
negativo,  representa  el  numero  de  caracteres  desde  el  final  de  cadena  en  los  que  dejar  de  sustituir.  Si  no 
se  especifica,  valdra  por  defecto  strlen(cadena);  es  decir,  que  acabara  la  sustitucion  al  final  de  cadena. 


Ejemplo  1.  Ejemplo  de  substr_replace() 

<?php 

$var  =  '  ABCDEFGH : /MNRPQR/ '  ; 
echo  "Original:  $var<hr>\n"; 

/*  Estos  dos  ejemplos  sustituyen  toda  $var  por  'bob' .  */ 

echo  substr_replace  ($var,  'bob',  0)  .  "<br>\n"; 

echo  substr_replace  ($var,  'bob',  0,  strlen  ($var) )  .  "<br>\n"; 

/*  Inserta  'bob'  justo  al  inicio  de  $var .  */ 
echo  substr_replace  ($var,  'bob',  0,  0)  .  "<br>\n"; 

/*  Los  dos  siguientes  cambian  'MNRPQR'  en  $var  por  'bob' .  */ 
echo  substr_replace  ($var,  'bob',  10,  -1)  .  "<br>\n"; 

echo  substr_replace  ($var,  'bob',  -7,  -1)  .  "<br>\n"; 

/*  Borrar  'MNRPQR'  de  $var .  */ 

echo  substr_replace  ($var,  ",  10,  -1)  .  "<br>\n"; 

?> 


Vea  tambien  str  replace ')  y  substr'). 

Nota:  substr_replace()  fue  anadida  en  el  PHP  4.0. 


trim 


(PHP  3,  PHP  4  >=  4.0.0) 


Elimina  espacios  del  principio  y  final  de  una  cadena 
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string  trim  (string  cad) 


Esta  funcion  elimina  los  espacios  en  bianco  del  comienzo  y  del  final  de  una  cadena  y  devuelve  el 
resultado.  Los  caracteres  de  espacio  que  elimina  realmente  son:  "\n",  "\r",  "\t",  "\v",  "\0",  y  el  espacio  en 
si. 

Vea  tambien  chop))  y  ltrim(). 


ucfirst  (PHP  3,  PHP  4  >=  4.0.0) 

Pasar  a  mayusculas  el  primer  caracter  de  una  cadena 

string  ucfirst  (string  cad) 


Pone  en  mayusculas  el  primer  caracter  de  cad  si  es  alfabetico. 

Notese  que  ’alfabetico’  esta  determinado  por  la  localidad  actual.  Por  ejemplo,  en  la  localidad  por  defecto 
"C",  los  caracteres  como  la  a  con  dieresis  (a)  no  seran  convertidos. 

Ejemplo  1.  Ejemplo  de  ucfirst() 

$texto  =  ' susanita  tiene  un  raton,  un  raton  chiquitin.'; 

$texto  =  ucfirst  ($texto) ;  //  $texto  vale  ahora:  Susanita  tiene  un 
//  raton,  un  raton  chiquitin. 


Vea  tambien  strtoupper))  y  strtolower  ') 


ucwords  (PHP  3>=  3.0.3,  PHP  4  >=  4.0.0) 

Pone  en  mayusculas  el  primer  caracter  de  cada  palabra  de  una  cadena 

string  ucwords  (string  cad) 


Pasa  a  mayusculas  la  primera  letra  de  cada  palabra  en  cad  si  dicho  caracter  es  alfabetico. 
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Ejemplo  1.  Ejemplo  de  ucwords() 

$texto  =  "susanita  tiene  un  raton,  un  raton  chiquitin."; 

$texto  =  ucwords ($texto) ;  //  $texto  vale  ahora:  Susanita  Tiene  Un 

//  Raton,  Un  Raton  Chiquitin. 


Vea  tambien  strtouppeL),  strtolowerj)  y  ucfirst'). 


wordwrap  (php  4  >=4o  2) 

Corta  una  cadena  en  un  numero  dado  de  caracteres  usando  un  caracter  de  ruptura  de  cadenas. 

string  wordwrap  (string  cad  [,  int  ancho  [,  string  ruptura]]) 


Corta  la  cadena  cad  en  la  columna  especificada  por  el  parametro  (opcional)  ancho.  La  lfnea  se  rompe 
utilizando  el  parametro  (opcional)  ruptura. 

wordwrap))  automatic amente  cortara  en  la  columna  75  y  usara  ’\n’  (nueva  lfnea)  si  no  se  especifican  el 

ancho  o  la  ruptura. 


Ejemplo  1.  Ejemplo  de  wordwrapO 

$texto  =  "El  veloz  murcielago  hindu  comia  feliz  cardillo  y  kiwi."; 
$textonuevo  =  wordwrap (  $texto,  20  ); 

echo  " $textonuevo\n" ; 


Este  ejemplo  mostrarfa: 

El  veloz  murcielago 

hindu  comia  feliz  cardillo  y  kiwi. 


Vea  tambien  nl2br0- 


1072 


LXXXIV.  Funciones  de  Sybase 


1073 


Sybase 


sy  base_affected_rows  (php  3>=  3.0.6,  php  4  >=  4  0  o> 

obtiene  el  numero  de  filas  afectadas  por  la  ultima  consulta 

int  sybase_af fected_rows  (int  [link_identifier]) 


Devuelve:  El  numero  de  filas  afectadas  por  la  ultima  consulta. 

sybase_affected_rows()  devuelve  el  numero  de  filas  afectadas  por  la  ultima  accion  e  tipo  INSERT, 
UPDATE  o  DELETE  en  el  servidor  asociado  al  identificador  de  enlace  especificado.  Si  no  se  especifica 
un  identificador  de  enlace,  se  asume  el  ultimo  enlace  abierto. 

Esta  instruccion  no  es  efectiva  para  sentencias  de  tipo  SELECT,  solo  en  sentencias  que  modifican 
registros.  Para  obtener  el  numero  de  filas  afectadas  por  un  SELECT,  use  sybase_num_rows  '). 

Nota:  Esta  funcion  solo  esta  disponible  usando  el  interface  de  la  librerfa  CT,  y  no  con  la  libreria  DB. 


sybase_close  (PHP  3,  PHP  4  >=  4.0.0) 

cierra  una  conexion  Sybase 

int  sybase_close  (int  link_identifier) 


Devuelve:  true  si  lo  consigue,  false  ante  un  error 

sybase_close()  cierra  el  enlace  a  la  base  de  datos  Sybase  asociada  con  el  identificador  de  enlace 
especificado.  Si  no  se  especifica  un  identificador  de  enlace,  se  asume  el  ultimo  enlace  abierto. 

Note  que  esto  no  es  necesario  usualmente,  ya  que  los  enlaces  no  persistentes  abiertos  son  cerrados 
automaticamente  al  final  de  la  ejecucion  del  script. 

sybase_close()  no  cerrara  enlaces  persistentes  generados  por  sybase_pconnect(). 

Vea  tambien:  sybase_connect\),  sybase_pconnectO- 


sybase_connect  (PHP  3,  PHP  4  >=  4.0.0) 

abre  una  conexion  con  un  servidor  Sybase 

int  sybase_connect  (string  servername ,  string  username ,  string  password) 
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Devuelve:  Un  identificador  de  enlace  Sybase  positivo,  o  false  ante  un  error. 

sybase_connect()  establece  una  conexion  son  un  servidor  Sybase.  El  parametro  servername  tiene  que  ser 
un  nombre  de  servidor  valido  que  esta  definido  en  el  fichero  ’interfaces’. 

En  el  caso  que  se  haga  una  segunda  llamada  a  sybase_connect()  con  los  mismos  argumentos,  no  se 
establecera  un  nuevo  enlace,  en  vez  de  esto,  se  devolvera  el  identificador  de  enlace  que  ya  esta  abierto. 

El  enlace  al  servidor  sera  cerrado  tan  pronto  como  la  ejecucion  del  script  finalice,  a  menos  que  sea 
cerrado  antes  llamando  explicitamente  a  sybase_close 

Vea  tambien  sybase_pconnect3,  sybase_close '). 


sybase_data_seek  (PHP  3,  PHP  4  >=  4.0.0) 

mueve  el  puntero  interno  de  la  fila 

int  sybase_data_seek  (int  result_identifier,  int  row_number ) 


Devuelve:  true  si  lo  hace,  false  en  caso  de  fallo 

sybase_data_seek()  mueve  el  puntero  interno  de  la  fila  del  resultado  asociado  con  el  identificador  de 
resultado  especificado  hacia  el  numero  de  fila  introducido.  La  siguiente  llamada  a  sybase_fetch_rowO 
devolvera  esa  fila. 

Vea  tambien:  sybase_data_seek(). 


sybasejfetcharray  (php  3  php  4  >=  4.o.o) 

carga  una  fila  como  un  array 

int  sybase_fetch_array  (int  result) 


Returns:  An  array  that  corresponds  to  the  fetched  row,  or  false  if  there  are  no  more  rows. 

sybase_fetch_array()  es  la  version  extendida  de  sybase_fetch_row ').  Ademas  de  almacenar  los  datos  en 
los  indices  numericos  del  array  de  resultados,  tambien  almacena  los  datos  en  indices  asociativos,  usando 
los  nombres  de  campo  como  claves. 

Una  cosa  importante  a  remarcar  es  que  el  uso  de  sybase_fetch_array()  NO  es  signihcativamente  mas 
lento  que  el  uso  de  sybase_fetch_row(),  mientras  que  proporciona  un  valor  anadido  significativo. 

Para  mas  detalles,  vea  tambien  sybase_fetch_rowO 
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sybasejfetchf  ield  (php  3,  php  4  >=  4 .0 .0) 

obtiene  la  informacion  del  campo 

object  sybase_fetch_field  (int  result,  int  field_offset) 


Devuelve  un  objeto  conteniendo  la  informacion  del  campo 

sybase_fetch_field()  puede  usarse  para  obtener  informacion  sobre  los  campos  de  una  consulta 
determinada.  Si  no  se  especifica  el  offset  del  campo,  el  siguiente  campo  que  aun  no  halla  sido  tornado 
por  sybase_fetch_field()  es  el  que  se  obtiene. 

Las  propiedades  del  objeto  son: 

•  name  -  column  name,  si  la  columna  es  el  resultado  de  una  funcion,  esta  propiedad  se  establece  a 
computed#N,  donde  #N  es  un  numero  de  serie. 

•  column_source  -  la  tabla  de  la  cual  se  ha  cogido  la  columna 

•  max_length  -  maxima  longitud  de  la  columna 

•  numeric  -  1  si  la  columna  es  numerica 
Vea  tambien  sybase_field_seekO 


sybase_fetch_object  <php  3,  php  4  >=  4.o.0) 


carga  una  fila  como  un  objeto 


int  sybase_fetch_ob ject  (int  result) 


Devuelve:  Un  objeto  con  las  propiedades  que  corresponden  a  la  fila  tomada,  o  false  si  no  hay  mas  filas. 

sybase_fetch_object()  es  similar  a  sybase_fetch_array(),  con  una  diferencia  -  se  devuelve  un  objeto,  en 
vez  de  un  array.  Indirectamente,  esto  significa  que  solo  se  puede  acceder  a  los  datos  por  los  nombres  de 
campo,  y  no  por  sus  offsets  (los  numeros  son  nombres  de  propiedades  ilegales). 

En  el  tema  de  velocidad,  la  funcion  es  identica  a  sybase_fetch_array(),  y  al  menos  tan  rapida  como 
sybase_fetch_row ')  (la  diferencia  es  insignificante). 

Vea  tambien:  sybase_fetch-array()  y  sybase_fetch-row(). 


sybase_fetch_row  (php  3  PHP  4  >=  4 .0 .0 


obtiene  una  fila  como  un  array  enumerado 


1076 


Sybase 


array  sybase_fetch_row  (int  result) 


Devuelve:  Un  array  que  corresponde  a  la  fila  obtenida,  o  false  si  no  hay  mas  filas. 

sybase_fetch_row()  obtiene  una  fila  de  datos  del  resultado  asociado  con  el  identificador  de  resultado 
especificado.  La  fila  se  devuelve  como  un  array.  Cada  columna  del  resultado  es  almacenada  en  un  offset 
del  arrat,  comenzando  en  el  offset  0. 

Las  siguientes  llamadas  a  sybase_fetch_rows()  devolveran  la  siguiente  fila  del  conjunto  de  resultados,  o 
false  si  no  hay  mas  filas. 

Vea  tambien:  sybase_fetch_arrayO,  sybase_fetch_object'),  sybase_data_seek '),  sybase_fetch_lengths(), 
y  sybase_resultO. 


sybase_f  ield_seek  (php  3,  php  4  >=  4.0.0 

establece  el  offset  de  un  campo 

int  sybase_f ield_seek  (int  result,  int  field_offset) 

Localiza  el  campo  especificado  por  el  offset.  Si  la  siguiente  llamada  sybase_fetch_field ')  no  incluye  un 
offset  se  devuelve  este  campo. 

Vea  tambien:  sybase_fetch_fiekL). 


sybase_f ree_result  (php  3,  php  4  >=  4.0.0 


libera  el  resultado  de  la  memoria 


int  sybase_free_result  (int  result) 


sybase_free_result()  solo  se  necesita  usar  en  el  caso  de  que  este  preocupado  por  el  uso  de  demasiada 
memoria  mientras  se  ejecuta  su  script.  Todos  los  resultados  en  memoria  son  liberados  cuando  el  script 
finaliza,  puede  llamar  a  sybase_free_result()  con  el  identificador  de  resultado  como  argumento  y  la 
memoria  asociada  a  ese  resultado  sera  liberada. 


sybase_num_f ields  <php  3  php 4 >=  4.o.o 


obtiene  el  numero  de  campos  de  un  resultado 
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int  sybase_num_f ields  (int  result) 

sybase_num_fields()  devuelve  el  numero  de  campos  en  un  conjunto  de  resultados. 

Vea  tambien:  sybase_db_query(),  sybase_query sybase_fetch_beld\),  sybase_num_rows'). 


sybase_num_rows  (php  3,  php  4  >=  4.0.0) 

obtiene  el  numero  de  bias  de  un  resultado 

int  sybase_num_rows  (string  result) 

sybase_num_rows()  devuelve  el  numero  de  bias  de  un  conjunto  de  resultados. 
Vea  tambien:  sybase_db_query(),  sybase_query ')  and,  sybase_fetch_row '). 


sybase_pconnect  (php  3,  PHP  4  >=  4 .0.0 

abre  una  conexion  con  Sybase  persistente 

int  sybase_pconnect  (string  servername,  string  username ,  string  password) 


Devuelve:  Un  identibcador  de  enlace  persistente  de  Sybase  positivo  en  caso  de  que  pueda  abrirlo,  en 
caso  de  error  devuelve  false 

sybase_pconnect()  actua  de  una  forma  muy  parecida  a  sybase_conncct ')  con  dos  grandes  diferencias. 

Primera,  cuando  se  conecta,  esta  funcion  primero  tratara  de  encontrar  un  enlace  (persistente)  que  ya  este 
abierto  con  el  mismo  host,  nombre  de  usuario  y  contrasena.  Si  encuentra  uno,  devolvera  un  identibcador 
para  el  en  vez  de  abrir  una  nueva  conexion. 

Segunda,  la  conexion  al  servidor  SQL  no  se  cerrara  cuando  bnalice  la  ejecucion  del  script.  En  vez  de 
esto,  el  enlace  permanecera  abierto  para  un  futuro  uso  (sybase_close  J  no  podra  cerrar  enlaces 
establecidos  consvbase  pconnect  ( )  ). 

Este  tipo  de  enlaces  son  llamados  ’persistentes’. 


sybase_query  php 3  PHP 4 >=  4.o.0) 


envia  una  consulta  a  Sybase 
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int  sybase_query  (string  query,  int  link_identifier) 


Devuelve:  Un  identificador  de  resultado  Sybase  positivo  si  va  bien,  o  false  ante  un  error. 

sybase_query()  envfa  una  consulta  a  la  actual  base  de  datos  activa  en  el  servidor  que  esta  asociada  con  el 
identificador  de  enlace  especificado.  Si  no  se  especifica  un  identificador  de  enlace,  se  asume  el  ultimo 
enlace  abierto.  Si  no  hay  un  enlace  abierto,  la  funcion  intentara  establecer  un  enlace  como  si 
sybase_connect  ')  fuese  llamada,  y  lo  usara. 

Vea  tambien:  sybase_db_query(),  sybase_select_db '),  y  sybase_conncct  ). 


sybase_result  (PHP3,  PHP  4  >=  4.0.0) 


obtiene  datos  de  un  resultado 


int  sybase_result  (int  result,  int  i,  mixed  field) 


Devuelve:  El  contenido  de  la  celda  en  la  fila  y  el  offset  especificado  de  un  conjunto  de  resultados  de 
Sybase. 

sybase_result()  devuelve  el  contenido  de  una  celda  de  un  conjunto  de  resultados  de  Sybase.  El  parametro 
field  puede  ser  el  offset  del  campo,  o  el  nombre  del  campo,  o  el  nombre  de  la  tabla,  un  punto  y  el  nombre 
del  campo  (nombre_tabla.nombre_campo).  Si  el  nombre  de  la  columna  tiene  un  alias  (’select  foo  as  bar 
from...’),  use  el  alias  en  vez  del  nombre  de  la  columna. 

Cuando  trabaje  con  conjuntos  de  resultados  grandes,  debe  considerar  el  uso  de  alguna  de  las  funciones 
que  cargan  una  fila  entera  (especificadas  abajo).  Ya  que  estas  funciones  devuelven  el  contenido  de 
multiples  celdas  en  una  unica  llamada,  son  MUCHO  mas  rapidas  que  sybase_result().  Ademas,  note  que 
especificar  un  offset  numerico  en  el  parametro  field  es  mucho  mas  rapido  que  especificar  un  nombre  de 
campo  o  nombre_tabla.nombre_campo. 

Alternativas  recomendadas  para  alto  rendimiento:  sybase_fetch_row '),  sybase_fetch_array '),  y 
sybase_fetch_obj  ect') . 


sybase_select_db  (PHP  3,  PHP  4  >=  4.0.0) 

seleccciona  una  base  de  datos  Sybase 

int  sybase_select_db  (string  database_name,  int  link_identifier) 


Returns:  true  on  success,  false  on  error 
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sybase_select_db()  establece  como  activa  la  base  de  datos  en  el  servidor  asociada  con  el  identificador  de 
enlace  especificado.  Si  no  se  especifica  un  identificador  de  enlace,  se  asume  el  ultimo  enlace  abierto.  Si 
no  hay  un  enlace  abierto,  la  funcion  intentara  establecer  un  enlace  como  si  sybase_connect')  fuese 
llamada,  y  lo  usara. 

Cada  llamada  subsiguiente  a  sybase_query ')  sera  hecha  en  la  base  de  datos  activa. 

Vea  tambien:  sybase_connect'),  sybase_pconnect'),  y  sybase_query  3 
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base64_decode  (PHP  3,  PHP  4  >=  4.0.0) 

decodifica  datos  cifrados  con  MIME  base64 

string  base64_decode  (string  datos_cifrados) 

base64_decode()  decodifica  datos_cifrados  y  devuelve  los  datos  originates.  Los  datos  devueltos 
pueden  ser  binarios. 

Vea  tambien:  base64_encode  ),  RFC-2045  seccion  6.8. 


base64_encode  (PHP  3,  PHP  4  >=  4.0.0) 


Codifica  datos  en  MIME  base64 


string  base64_encode  (string  datos ) 


base64_encode()  devuelve  datos  cifrados  en  base64.  Esta  codification  esta  pensada  para  que  los  datos 
binarios  sobrevivan  al  transporte  a  traves  de  capas  que  no  son  de  8  bits,  como  por  ejemplo  los  cuerpos  de 
los  mensajes  de  correo. 

Los  datos  codificados  con  Base64  ocupan  aproximadamente  un  33%  mas  de  espacio  que  los  datos 
originates. 

Vea  tambien:  base64_decodeQ,  chunk  split'),  RFC-2045  seccion  6.8. 


parse_url 


(PHP  3,  PHP  4  >=4.0.0) 


Analiza  una  URL  y  devuelve  sus  componentes 


array  parse_url  (string  url) 


Esta  funcion  devuelve  una  matriz  que  apunta  a  alguno  de  los  componentes  de  la  URL  que  esten 
presentes.  Esto  incluye  el  "esquema",  "host",  "puerto",  "usuario",  "pass",  "path",  "consulta",  y 
"fragmento". 
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urldecode  (PHP  3,  PHP  4  >=  4.0.0) 

decodifica  URL-cifradas  en  una  cadena  de  texto 


string  urldecode  (string  cadena) 


Decodifica  cualquier  %##  cifrado  en  la  cadena  dada.  Se  devuelve  la  cadena  decodificada. 

Ejemplo  1.  Ejemplo  urldecode() 

$a  =  split  $querystring)  ; 

$i  =  0; 

while  ($i  <  count  ( $  a ) )  { 

$b  =  split  $a  [  $ i ] ) ; 

echo  'El  valor  para  el  parametro  htmlspecialchars  (urldecode  ($b  [0])), 
'  es  ' ,  htmlspecialchars  (urldecode  ($b  [1])),  "<BR>"; 

$  i  +  t  r 

} 


Vea  tambien  urlencodeO 


urlencode  (PHP  3,  PHP  4  >=4.0.0) 

Codifica  una  URL  en  una  cadena  de  texto 

string  urlencode  (string  cadena) 


Devuelve  una  cadena  en  la  que  todos  los  caracteres  no  alfanumericos  excepto  han  sido 
reemplazados  con  un  signo  de  porcentaje  (%)  seguido  por  dos  dfgitos  hexadecimales  y  los  espacios  han 
sido  codificados  como  signos  positivos  (+).  Esta  codificado  de  la  misma  manera  que  los  datos  que  se 
envian  desde  un  formulario  WWW,  es  decir  de  la  misma  forma  que  el  tipo 

application/x-www-form-urlencoded.  Esto  difiere  del  cifrado  RFC1738  (vea  rawurlencodef)  ) 
en  el  que  por  razones  historicas,  los  espacios  son  codificados  como  signos  positivos  (+  ).  Esta  funcion  es 
conveniente  para  codificar  una  cadena  de  texto  que  va  a  ser  usada  como  parte  de  una  consulta  de  una 
URL,  y  es  una  forma  adecuada  de  pasar  variables  a  la  pagina  siguiente: 

Ejemplo  1.  Ejemplo  urlencode() 

echo  '  <A  HREF="mycgi?foo=' ,  urlencode  ($userinput)  , 


Vea  tambien  urldecode() 
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doubleval  (PHP3,  PHP  4  >=  4.0.0) 

Obtiene  el  valor  double  (decimal)  de  una  variable. 

double  doubleval  (mixed  var ) 

Devuelve  el  valor  double  (decimal  en  punto  flotante)  de  var. 

var  puede  ser  cualquier  tipo  escalar.  No  se  puede  usar  doubleval()  sobre  arrays  u  objetos. 

Ver  tambien  intvalO,  strval'),  settype')  y  Type  juggling 

empty  (unknown) 

Determina  si  una  variable  esta  definida 

int  empty  (mixed  var) 

Devuelve  false  si  var  esta  definida  y  tiene  un  valor  no-vacfo  o  distinto  de  cero;  en  otro  caso  devuelve 

TRUE. 

Ver  tambien  isset))  y  unset)). 


gettype  (PHP  3,  PHP  4  >=4.0.0) 

Obtiene  el  tipo  de  una  variable. 

string  gettype  (mixed  var) 


Devuelve  el  tipo  de  la  variable  PHP  var. 

Los  valores  posibles  de  la  cadena  devuelta  son: 

•  "integer" 

•  "double" 

•  "string" 

•  "array" 

•  "object" 
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•  "unknown  type" 

Ver  tambien  settypej). 

intval  (PHP  3,  PHP  4  >=  4.0.0) 

Obtiene  el  valor  entero  de  una  variable. 

int  intval  (mixed  var  [,  int  base]) 

Devuelve  el  valor  entero  de  var,  usando  la  base  de  conversion  especificada  (por  defecto  es  base  10). 
var  puede  ser  cualquier  tipo  escalar.  No  se  puede  usar  intval()  sobre  arrays  u  objetos. 

Ver  tambien  doublevalj),  strval)),  settypej)  y  Type  juggling 

is_array  (PHP  3,  PHP  4  >=4.0.0) 

Averigua  si  una  variable  es  un  array. 

int  is_array  (mixed  var) 

Devuelve  true  si  var  es  un  array,  y  false  en  otro  caso. 

Ver  tambien  is_double(),  is_floaO,  is_int(),  is_integer  j,  is_real'),  is_string(),  is_long'),  y  is_object'). 

is_double  (PHP  3,  PHP  4  >=  4.0.0) 

Averigua  si  una  variable  es  un  valor  double  (numero  decimal). 

int  is_double  (mixed  var) 

Devuelve  true  si  var  es  un  double  (numero  decimal),  y  false  en  otro  caso. 

Ver  tambien  is_array '),  is_float(),  is_int '),  is_integer(),  is_real(),  is_string '),  is_long'),  y  is_object  [). 
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is_float  (PHP  3,  PHP  4  >=  4.0.0) 

Averigua  si  una  variable  es  un  flotante. 

int  is_float  (mixed  var) 

Esta  funcion  es  un  alias  de  is_double0- 

Ver  tambien  is_double(),  is_real[),  is_int(),  is_integer(),  is_string'),  is_object(),  is_array(),  y  is_long(). 

isjnt  (PHP  3,  PHP  4  >=  4.0.0) 

Averigua  si  una  variable  es  un  valor  entero. 

int  is_int  (mixed  var) 

Esta  funcion  es  un  alias  de  is_long '). 

Ver  tambien  is_double(),  is_float3,  is_integer'),  is_string3,  is_real'),  is_object(),  is_array(),  y  is_long(). 

isjnteger  (PHP  3,  PHP  4  >=4.0.0) 

Averigua  si  una  variable  es  un  valor  entero. 

int  is_integer  (mixed  var) 

Esta  funcion  es  un  alias  de  is_long '). 

Ver  tambien  is_double(),  is_float(),  is_int '),  is_string  ),  is_real(),  is_object0,  is_array(),  y  is_long(). 

isjong  (PHP  3,  PHP  4  >=  4.0.0) 

Averigua  si  una  varible  es  un  valor  entero. 

int  is_long  (mixed  var) 
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Devuelve  true  si  var  es  un  entero  (long),  y  false  en  otro  caso. 

Ver  tambien  is_double  '),  is_float(),  is_int(),  is_real  (),  is_string(),  is_object  '),  is_array'),  y  is_integei\). 

is_object  (PHP  3,  PHP  4  >=  4.0.0) 

Averigua  si  una  varible  es  un  objeto. 

int  is_object  (mixed  var) 

Devuelve  true  si  var  es  un  objeto,  y  false  en  otro  caso. 

Ver  tambien  is_long '),  is_int(),  is_integer'),  is_float(),  is_double'),  is_real '),  is_string  '),  y  is_array(). 

is_real  (PHP  3,  PHP  4  >=  4.0.0) 

Averigua  si  una  varible  es  un  numero  real. 

int  is_real  (mixed  var) 

Esta  funcion  es  un  alias  de  is_double  ')- 

Ver  tambien  is_long(),  is_int(),  is_integei\),  is_float(),  is_double'),  is_object0,  is_string(),  y  is_array(). 

is_string  (PHP  3,  PHP  4  >=4.0.0) 

Averigua  si  una  varible  es  una  cadena  de  caracteres  (string). 

int  is_string  (mixed  var ) 

Devuelve  true  si  var  es  una  cadena,  y  false  en  otro  caso. 

Ver  tambien  is_long '),  is_int(),  is_integer(),  is_float(),  is_double/),  is_reaE),  is_object(),  y  is_array(). 
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Variables 


isset  (unknown) 

Determina  si  una  varible  esta  definida 

int  isset  (mixed  var) 


Devuelve  true  si  var  existe;  y  false  en  otro  caso. 

Si  una  variable  ha  sido  destruida  con  unset  )),  ya  no  estara  definida  (no  sera  isset()). 

$a  =  "test"; 

echo  isset ( $  a ) ;  //  true 

unset ( $  a ) ; 

echo  isset  ($a) ;  //  false 


Ver  tambien  empty))  y  unset)). 


settype  (PHP  3,  PHP  4  >=  4.0.0) 

Establece  el  tipo  de  una  variable. 

int  settype  (string  var,  string  type) 


Establece  el  tipo  de  la  varible  var  como  type. 
Los  valores  posibles  para  type  son: 

•  "integer" 

•  "double" 

•  "string" 

•  "array" 

•  "object" 


Devuelve  true  si  se  lleva  a  cabo  con  exito;  en  otro  caso  devuelve  false. 
Ver  tambien  gettype)). 
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strval  (PHP3,  PHP  4  >=  4.0.0) 

Obtiene  una  cadena  de  caracteres  a  partir  de  una  variable. 

string  strval  (mixed  var) 

Devuelve  una  cadena  con  el  valor  de  var. 

var  puede  ser  cualquier  tipo  escalar.  No  se  puede  usar  strval()  sobre  arrays  u  objetos. 
Ver  tambien  doubleval)),  intval '),  settype))  y  Type  juggling 

unset  (unknown) 

Destruye  una  variable  dada 

int  unset  (mixed  var) 

unset()  destruye  la  variable  especificada  y  devuelve  true. 

Ejemplo  1.  Ejemplo  de  unset() 

unset (  $foo  )  ; 

unset (  $bar['quux']  ); 

Ver  tambien  isset))  y  empty)). 
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Estas  funciones  permiten  el  uso  de  WDDX  (http://www.openwddx.org/). 

Debe  saber  que  todas  las  funciones  que  serializan  variables  usan  el  primer  elemento  de  un  array  para 
determinar  si  este  ha  de  serializarse  en  forma  de  array  o  como  estructura.  Si  el  primer  elemento  esta 
indexado  por  una  cadena,  se  serializa  como  estructura,  y  en  caso  contrario,  como  array. 

Ejemplo  1.  Serializacion  de  un  valor  simple 

<?php 

print  wddx_serialize_value ( "Ejemplo  de  PHP  a  paquete  WDDX",  "Paquete  PHP"); 
?> 


Este  ejemplo  producira: 

<wddxPacket  version='  0 . 9 '  xheader  comment  =  ' Paquete  PHP'/xdata> 
<string>E jemplo  de  PHP  a  paquete  WDDX</string></data></wddxPacket> 


Ejemplo  2.  Uso  de  paquetes  incrementales 

<?php 

$pi  =  3.1415926; 

$packet_id  =  wddx_packet_start ( "PHP " )  ; 
wddx_add_vars ($packet_id,  "pi") ; 

/*  Suponga  que  $ciudades  se  ha  obtenido  de  una  base  de  datos  */ 
$ciudades  =  array ( "Austin" ,  "Novato",  "Seattle"); 
wddx_add_vars ( $packet_id,  "ciudades") ; 

$packet  =  wddx_packet_end ( $packet_id) ; 
print  $packet; 

?> 


Este  ejemplo  producira: 

<wddxPacket  version='  0 . 9 '  xheader  comment  =  '  PHP '  / xdataxstruct > 

<var  name='  pi '  ><number>3 .1415926</ number x/varxvar  name='  ciudades '  > 
<array  length=' 3' ><string>Austin</ stringXstring>Novato</ string> 
<string>Seattle</  stringx/  arrayx/varx/structx/  datax/wddxPacket> 
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wddx_serialize_value  (php  3>=  3.0.7,  php  4  >=  4.0.0 

Serializa  un  valor  simple  en  un  paquete  WDDX 

cadena  wddx_serialize_value  (varios-tipos  var  [,  cadena  comentarlo] ) 


wddx_serialize_value()  se  utiliza  para  crear  un  paquete  WDDX  desde  un  valor  simple  dado.  Toma  el 
valor  contenido  en  var,  y  una  cadena  comentario  opcional  que  aparecera  en  la  cabecera  del  paquete, 
y  devuelve  el  paquete  WDDX. 


wddx_serialize_vars  <php  3>=  3  0  7  php  4  >=  4.0.0 


Serializa  variables  en  un  paquete  WDDX 


cadena  wddx_serialize_vars  (varios-tipos  nombre_var  [,  varios-tipos  ...]) 


wddx_serialize_vars()  se  utiliza  para  crear  un  paquete  WDDX  con  una  estructura  que  contiene  la 
representacion  serializada  de  las  variables  pasadas  como  parametros. 

wddx_serialize_vars()  toma  un  numero  variable  de  argumentos,  cada  uno  de  los  cuales  puede  ser  una 
cadena  con  el  nombre  de  una  variable  o  un  array  con  nombres  de  variables,  o  de  otro  array,  etc. 


Ejemplo  1.  wddx_serialize_vars  example 

<?php 
$a  =  1; 

$b  =  5.5; 

$c  =  array ( "azul" ,  "naranja",  "violeta"); 

$d  =  "colores"; 

$clvars  =  array ("c",  "d"); 

print  wddx_serialize_vars ( "a"  ,  "b",  $clvars) ; 

?> 


El  ejemplo  anterior  producira: 

<wddxPacket  version='  0.9'  xheader/xdataxstructxvar  name='  a'  ><number>l</ number ></ var > 
<var  name='  b'  ><number>5 . 5</numberx/varXvar  name=' c' Xarray  length='3'> 

<string>azul</  stringxstring>naran  ja</  string><string>violeta</string></  arrayx/var> 

<var  name='  d'  ><string>colores</ stringx/varx/ structx/data></wddxPacket> 
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wddx_packet_start  (php  3>=  3.0.7,  php  4  >=  4  0  o> 

Comienza  un  nuevo  paquete  WDDX  con  una  estructura  dentro 

entero  wddx_packet_start  ( [cadena  comentario ] ) 


Utilice  wddx_packet_start()  para  comenzar  un  nuevo  paquete  WDDX  que  permita  la  adicion  sucesiva 
de  variables.  Recibe  el  parametro  opcional  comentario  y  devuelve  un  identificador  de  paquete  para  su 
uso  en  posteriores  llamadas.  Automaticamente  define  una  estructura  dentro  del  paquete  para  contener  las 
variables. 


wddx_packet_end  <php  3>=  3  0  7  php  4  >=  4  0  0) 

Finaliza  un  paquete  WDDX  con  el  identificador  dado 

cadena  wddx  packet  end  (entero  packet_id) 


wddx_packet_end()  finaliza  el  paquete  WDDX  especificado  por  el  packet_id  y  devuelve  la  cadena 
con  el  paquete. 


wddx_add_vars  (PHP  3>=  3.0.7,  PHP  4  >=  4.0.0) 

Finaliza  un  paquete  WDDX  con  el  identificador  dado 

wddx_add_vars  (entero  packet_id,  varios-tipos  name_var  [,  varios-tipos  ...]) 


wddx_add_vars()  se  utiliza  para  serializar  las  variables  dadas  e  incorporar  el  resultado  al  paquete 
especificado  por  packet_id.  Las  variables  a  serializar  se  especifican  exactamente  igual  que  en 
wddx_serialize_vars '). 
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wddxdeserialize  (php  3>=  3.0.7,  PHP  4  >=  4  0  o> 


Des-serializa  un  paquete  WDDX 


varios-tipos  wddx_deserialize  (cadena  packet) 


wddx_deserialized()  toma  una  cadena  packet  y  la  desserializa.  Devuelve  el  resultado  que  puede  ser  de 
tipo  cadena,  numerico  o  array.  Las  estructuras  son  desserializadas  en  forma  de  arrays  asociativos. 
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Introduccion 

Acerca  de  XML 

XML  (extensible  Markup  Language)  es  un  formato  de  informacion  para  el  intercambio  de  documentos 
estructurado  en  la  "Web"  Es  un  estandar  definido  por  el  consorcio  de  la  "World  Wide  Web"  (W3C).  Se 
puede  encontrar  informacion  sobre  XML  y  tecnologfs  relacionadas  en  http://www.w3.org/XML/. 


Instalacion 

Esta  extension  usa  expat,  que  se  puede  encontrar  en  http://www.jclark.com/xml/.  El  Makefile  que  viene 
con  expat  no  crea  una  biblioteca  por  defecto,  se  puede  usar  esta  regia  de  make  para  eso: 

libexpat.a:  $ (OBJS) 
ar  -rc  $@  $ (OBJS) 
ranlib  $@ 


Se  puede  conseguir  un  paquete  RPM  de  expat  en  http://sourceforge.net/projects/expat/. 

Nota  que  si  se  usa  Apache-1. 3. 7  o  posterior,  ya  tienes  la  biblioteca  requerida  expat.  Simplemente, 
configura  PHP  usando  — with-xml  (sin  ninguna  ruta  adicional)  y  usara  automaticamente  la  biblioteca 
expat  incluida  en  Apache. 

En  UNIX,  ejecuta  configure  con  la  opcion  — with-xml.  La  biblioteca  expat  deberfa  ser  instalada  en 
algun  lugar  donde  el  compilador  pueda  encontrarlo.  Si  se  compila  PHP  como  un  modulo  para  Apache 
1.3.9  o  posterior,  PHP  automaticamente  usara  la  biblioteca  integrada  expat  de  Apache.  Puede  necesitar 
establecer  CPPFLAGS  y  LDFLAGS  en  su  entorno  antes  de  ejecutar  "configure"  si  se  ha  instalado  expat 
en  algun  lugar  exotico. 

Compila  PHP.  jTa-tam!  Ya  deberfa  estar. 


Sobre  Esta  Extension 

Esta  extension  de  PHP  implementa  soporte  para  expat  de  James  Clarkin  en  PHP.  Este  conjunto  de 
herramientas  permite  interpretar,  pero  no  validar,  documentos  XML.  Soporta  tres  codificaciones  de 
caracteres  fuente,  tambien  proporcionados  por  PHP:  US-ASCII,  ISO-8859-1  y  UTF-8.  utf-16  no  esta 
soportado. 

Esta  extension  permite  crear  interpretes  de  XML  y  definir  entonces  gestores  para  diferentes  eventos 
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XML.  Cada  interprete  XML  tiene  tambien  unos  cuantos  parametros  que  se  pueden  ajustar. 
Los  gestores  de  eventos  XML  definidos  son: 


XML 


Tabla  1.  Gestores  de  XML  soportados 


Funcion  PHP  para  establecer  gestor 

Description  del  evento 

xml_set_element_handler') 

Los  eventos  de  elemento  ("element")  se  producen 
cuando  el  interprete  XML  encuentra  etiquetas  de 
comienzo  o  fin.  Hay  gestores  separados  para 
etiquetas  de  comienzo  y  etiquetas  de  fin. 

xml_set_charactcr_data_handlcr) 

La  informacion  de  caracteres  es,  por  definicion, 
todo  el  contenido  no  "marcado"  de  los  documentos 
XML,  incluidos  los  espacios  en  bianco  entre 
etiquetas.  Nota  que  el  interprete  XML  no  anade  o 
elimina  ningun  espacio  en  bianco,  depende  de  la 
aplicacion  (de  ti)  decidir  si  el  espacio  en  bianco  es 
significativo. 

xml_set_pmcessiiig_instruction_haiidlcr) 

Los  programadores  de  PHP  deberfan  estar  ya 
familiarizados  con  las  instrucciones  de  procesado 
(PI).  <?php  ?>  es  una  instruccion  de  procesado, 
donde  php  se  denomina  el  "objetivo  de  procesado". 
El  manejo  de  estos  es  especffico  a  cada  aplicacion, 
salvo  que  todos  los  objetivos  PI  que  comienzan  con 
"XML"  estan  reservados. 

xml_set_default_handler  i} 

Todo  lo  que  no  va  a  otro  gestor,  va  al  gestor  por 
defecto.  Se  tendran  en  el  gestor  por  defecto  cosas 
como  las  declaraciones  de  tipos  de  documento  y 
XML. 

xml_set_unparsed_entity_decl_handler') 

Este  gestor  se  llamara  para  la  declaracion  de  una 
entidad  no  analizada  (NDATA). 

xml_set_notation_decl_handler() 

Este  gestor  se  llama  para  la  declaracion  de  una 
anotacion. 

xml_set_external_entity_ref_handlerO 

Este  gestor  se  llama  cuando  el  interprete  XML 
encuentra  una  referenda  a  una  entidad  general 
interpretada  externa.  Puede  ser  una  referenda  a  un 
archivo  o  URL,  por  ejemplo.  Ver  el  ejemplo  de 
entidad  externa  para  demostracion. 

Case  Folding 

Las  funciones  manejadoras  de  elementos  pueden  tomar  sus  nombres  de  elementos  "case-folded" . 
Case-folding  se  define  en  el  estandar  XML  como  "un  proceso  aplicado  a  una  secuencia  de  caracteres,  en 
el  cual  aquellos  identificados  como  sin-mayusculas  son  reemplazados  por  sus  equivalentes  en 


1096 


XML 


mayusculas".  En  otras  palabras,  cuando  se  trata  de  XML,  case-folding  simplemente  significa  poner  en 
mayusculas. 

Por  defecto,  todos  los  nombres  de  elementos  que  se  pasan  a  las  funciones  gestoras  estan  "pasados  a 
mayusculas".  Esta  conducta  puede  ser  observada  y  controlada  por  el  analizador  XML  con  las  funciones 
xml_parser_get_option ')  y  xml_parser_set_option '),  respectivamente. 


Codigos  de  Error 

Las  siguientes  constantes  se  definen  para  codigos  de  error  XML  (como  los  devuelve  xml_parse')): 


XML_ERROR_NONE 
XML_ERROR_NO_MEMORY 
XML_ERROR_S  YNTAX 
XML_ERROR_NO_ELEMENTS 

xml_error_invalid_token 

XML_ERROR_UNCLOSED_TOKEN 

XML_ERROR_PARTIAL_CHAR 

XML_ERROR_TAG_MISMATCH 

XML_ERROR_DUPLICATE_ATTRIBUTE 

XMI  ._ERROR_.ll INKAFTERDOCET  .F.MF.NT 

XML_ERROR_PARAM_ENTITY_RFF 

XML_ERROR_UNDEFINED_ENTITY 

XML_ERROR_RECURSIVE_ENTITY_REF 

XML_ERROR_ASYNC_ENTITY 

xml_error_bad_char_ref 

XML_ERROR_BINARY_ENTITY_REF 

XML_ERROR_ATTRIBUTE_EXTERNAL_ENTITY_REF 

XML_ERROR_MISPLACED_XML_PI 

XML_ERROR_UNKNOWN_ENCODING 

XML_ERROR_INCORRECT_ENCODING 

XML_ERROR_UNCLOSED_CDATA_SECTION 

xml_error_external_entity_handling 


Codificacion  de  caracteres 

La  extension  XML  de  PHP  soporta  el  conjunto  de  caracteres  Unicode  (http://www.unicode.org/)  a  traves 
de  diferentes  codifcaciones  de  caracteres.  Hay  dos  tipos  de  codificaciones  de  caracteres,  coficacion  de 
fuente  y  codificacion  de  destino.  La  representacion  interna  de  PHP  del  documento  esta  siempre 
codificada  con  utf-8. 

La  codificacion  de  fuente  se  hace  cuando  un  documento  XML  es  interpretado  A1  crear  un  interprete 
XML  ,  se  puede  especificar  una  codificacion  de  fuente  (esta  codificacion  no  se  puede  cambiar  ma  tarde 
durante  el  tiempo  de  vida  del  interprete  XML).  Las  codificaciones  de  fuente  soportadas  son 
ISO-8859-1,  US— ASCI  I  y  utf-8.  Las  dos  primeras  son  codificaciones  de  byte-unico,  lo  que  significa 
que  cada  caracter  se  representa  por  un  solo  byte,  utf-8  puede  codificar  caracteres  compuestos  por  un 
numero  variable  de  bits  (hasta  21)  en  de  uno  a  cuatro  bytes.  La  codificacion  fuente  por  defecto  usada  por 
PHP  es  ISO-8859-1. 

La  codificacion  de  destino  se  hace  cuando  PHP  pasa  datos  a  las  funciones  gestoras  XML.  Cuando  se  crea 
un  interprete  XML,  la  codificacion  de  destino  se  crea  igual  a  la  codificacion  de  fuente,  pero  se  puede 
cambiar  en  cualquier  momento.  La  codificacion  de  destino  afectara  a  la  informacion  de  los  caracteres  as! 
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como  a  los  nombres  de  las  etiquetas  y  a  los  objetivos  de  instrucciones  de  procesado. 

Si  el  interprete  XML  encuentra  caracteres  fuera  del  rango  que  su  codificacion  de  fuente  es  capaz  de 
representar,  devolvera  un  error. 

Si  PHP  encuentra  caracteres  en  el  documento  XML  interpretado  que  no  pueden  ser  representados  en  la 
codificacion  de  destino  elegida,  los  caracteres  problema  seran  "degradados".  Actualmente,  esto  significa 
que  tales  caracteres  se  reemplazan  por  un  signo  de  interrogation. 


Algunos  Ejemplos 

Aquf  hay  algunos  ejemplos  de  archivos  de  comandos  PHP  que  interpretan  documentos  XML. 


Ejemplos  de  Estructuras  de  Elementos  XML 

Este  primer  ejemplo  muestra  la  estructura  del  elemento  inicio  en  un  documento  con  indentation. 

Ejemplo  1.  Muestra  la  Estructura  del  Elemento  XML 

$file  =  "data. xml"; 

$depth  =  array  () ; 

function  startElement (Sparser,  $name,  $attrs)  { 
global  $depth; 

for  ($i  =0;  $i  <  $depth [ Sparser ] ;  $i++)  { 

print  "  " ; 

} 

print  "$name\n"; 

$depth [ $parser] ++; 

} 

function  endElement (Sparser,  Sname)  { 
global  $depth; 

$ depth [Sparser] — ; 

} 

$xml_parser  =  xml  parser  create () ; 

xml_set_element_handler ( $xml_parser ,  "startElement",  "endElement") ; 
if  ( !  ($fp  =  fopen  ( $ f ile,  "r") ) )  { 

die ("could  not  open  XML  input"); 

} 

while  ($data  =  fread($fp,  4096))  { 

if  ( ! xml_parse ( $xml_parser ,  $data,  feof($fp)))  { 
die ( sprintf ( "XML  error:  %s  at  line  %d", 

xml  error  string (xml  get  error  code($xml  parser) ) , 
xml_get_current_line_number ( $xml_parser ) ) ) ; 

} 

} 
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xml_parser_f ree ( $xml_parser ) ; 


Ejemplo  de  Mapeo  de  Etiquetas  XML 


Ejemplo  2.  Traduciendo  XML  a  HTML 

Este  ejemplo  transforma  etiquetas  de  un  documento  XML  directamente  a  etiquetas  HTML.  Los 
elementos  no  encontrados  en  el  "array  de  traduccion  ("map  array")  son  ignorados.  Por  supuesto,  este 
ejemplo  solamente  funcionara  con  un  tipo  de  documentos  XML  especffico. 

$file  =  "data. xml"; 

$map_array  =  array ( 

"BOLD"  =>  "B", 

"EMPHASIS"  =>  "I", 

"LITERAL"  =>  "TT" 

)  ; 


function  startElement (Sparser,  $name,  $attrs)  { 
global  $map_array; 

if  ($htmltag  =  $map_array [ $name] )  { 

print  "<$htmltag>" ; 

} 

} 

function  endElement ( Sparser ,  $name)  { 
global  $map_array; 

if  ($htmltag  =  $map_array [ $name] )  { 

print  "</$htmltag>" ; 

} 

} 

function  characterData (Sparser,  Sdata)  { 
print  Sdata; 

} 

$xml_parser  =  xml  parser  create () ; 

/ /  usa  case-folding  para  que  estemos  seguros  de  encontrar  la  etiqueta 
//  en  $map_array 

xml  parser  set  option ($xml  parser,  XML_OPTION_CASE_FOLDING,  true) ; 
xml_set_element_handler ( $xml_parser ,  "startElement",  "endElement" ) ; 
xml_set_character_data_handler ( $xml_parser,  "characterData" ) ; 
if  ( !  ( $ f p  =  fopen  ( $ f ile,  "r") ) )  { 

die ("could  not  open  XML  input"); 

} 

while  (Sdata  =  fread($fp,  4096))  { 

if  ( ! xml_parse ( $xml_parser ,  Sdata,  feof($fp)))  { 
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die ( sprintf ( "XML  error:  %s  at  line  %d", 

xml  error  string (xml  get  error  code($xml  parser) ) , 
xml_get_current_line_number ( $xml_parser ) ) ) ; 

} 

} 

xml_parser_f ree ( $xml_parser ) ; 


Ejemplo  de  Entidad  Externa  XML 

Este  ejemplo  resalta  el  codigo  XML.  Ilustra  como  usar  un  gestor  de  referenda  de  entidades  extenas  para 
incluir  y  analizar  otros  documentos,  as!  como  cuuntos  Pis  pueden  ser  procesados,  y  un  modo  de 
determinar  "confianza"  para  Pis  que  contienen  codigo. 

Los  documentos  XML  que  se  pueden  usar  en  este  ejemplo  se  encuentran  bajo  el  ejemplo  (xmltest .  xml 
y  xmltest2  .  xml.) 

Ejemplo  3.  Ejemplo  de  Entidades  Externas 

$file  =  "xmltest . xml "  ; 
function  trustedFile  ($file)  { 

//  solamente  confia  en  archivos  locales  que  nos  pertenezcan 
if  (! eregi  (" A  (  [a-z ]+)://" ,  $file) 

&&  fileowner  ($file)  ==  getmyuidO)  { 
return  true; 

} 

return  false; 

} 

function  startElement (Sparser,  $name,  $attribs)  { 

print  "&lt;<font  color=\ " #0000cc\ ">$name</f ont>" ; 
if  ( sizeof ( $attribs ) )  { 

while  (list  ($k,  $v)  =  each  ( $attribs ) )  { 

print  "  <font  color=\ "#00 9900\ ">$k</f ont>=\ "<f ont 
color=\"#990000\">$v</font>\""; 

} 

} 

print  " & gt ; " ; 

} 

function  endElement ( Sparser ,  $name)  { 

print  "&lt;/<font  color=\ " #0000cc\ ">$name</f ont>&gt ; " ; 

} 

function  characterData (Sparser,  $data)  { 
print  "<b>$data</b>" ; 

} 
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function  PIHandler ( Sparser,  $target,  $data)  { 
switch  ( strtolower ( $target ) )  { 

case  "php" : 

global  $parser_f ile; 

//  Si  el  documento  analizado  es  "de  confianza",  diremos 
//  que  es  seguro  ejecutar  codigo  PHP  en  su  interior. 

//  Si  no,  en  vez  de  ello  mostrara  el  codigo. 
if  (trustedFile ( $parser_f ile [ Sparser ]) )  { 

eval ( $data) ; 

}  else  { 

printf ( "Untrusted  PHP  code:  <i>%s</i>", 
htmlspecialchars ($data) ) ; 

} 

break; 

} 

} 

function  def aultHandler ( Sparser ,  Sdata)  { 

if  ( substr ( Sdata,  0,  1)  ==  &&  substr ( Sdata,  -1,  1)  ==  { 

printf  ( ' <f ont  color="#aa00aa">%s</font>' , 
htmlspecialchars (Sdata) ) ; 

}  else  { 

printf  ( ' <f ont  size="-l">%s</ f ont>' , 
htmlspecialchars (Sdata) ) ; 

} 

} 


function  externalEntityRef Handler (Sparser,  SopenEntityNames ,  Sbase,  Ssystemld, 

Spublicld)  { 

if  (Ssystemld)  { 

if  (! list ( Sparser ,  $fp)  =  new_xml_parser (Ssystemld) )  { 

printf ( "Could  not  open  entity  %s  at  %s\n",  SopenEntityNames, 
Ssystemld) ; 
return  false; 

} 

while  (Sdata  =  fread($fp,  4096))  { 

if  (! xml_parse ( Sparser ,  Sdata,  feof ($fp) ) )  { 

printf ("XML  error:  %s  at  line  %d  while  parsing  entity  %s\n", 
xml_error_string (xml_get_error_code (Sparser) ) , 
xml_get_current_line_number ( Sparser ) ,  SopenEntityNames) 
xml_parser_f ree (Sparser) ; 
return  false; 

} 

} 

xml_parser_f ree (Sparser)  ; 
return  true; 

} 

return  false; 


function  new  xml  parser ( $f ile)  { 


1101 


XML 


global  $parser_f ile ; 

$xml_parser  =  xml  parser  create  0 ; 

xml  parser  set  option ($xml  parser,  XML_OPTION_CASE_FOLDING,  1); 
xml_set_element_handler ( $xml_parser ,  " startElement " ,  "endElement" ) ; 

xml_set_character_data_handler ($xml_parser,  "characterData" ) ; 
xml  set  processing  instruction  handler ( $xml_parser ,  "PIHandler" ) ; 
xml_set_def ault_handler ( $xml_parser ,  "def aultHandler " ) ; 

xml_set_external_entity_ref_handler ( $xml_parser ,  " ext ernalEntityRef Handler " ) 

if  ( ! ($fp  =  @fopen ($file,  "r" ) ) )  { 

return  false; 

} 

if  ( ! is_array ($parser_f ile) )  { 

settype ($parser_file,  "array") ; 

} 

$parser_f ile [ $xml_parser ]  =  $file; 
return  array ( $xml_parser,  $fp) ; 

} 

if  (! (list ($xml_parser,  $fp)  =  new_xml_parser ( $f ile) ) )  { 

die ("could  not  open  XML  input"); 

} 

print  "<pre>"; 

while  ($data  =  fread($fp,  4096))  { 

if  ( ! xml_parse ( $xml_parser ,  $data,  feof($fp)))  { 
die ( sprintf ( "XML  error:  %s  at  line  %d\n", 

xml  error  string (xml  get  error  code ($xml  parser) ) , 
xml_get_current_line_number ( $xml_parser ) ) ) ; 

} 

} 

print  "</pre>"; 

print  "parse  complete\n"; 

xml_parser_f ree ( $xml_parser ) ; 

?> 


Ejemplo  4.  xmltest.xml 

<?xml  version=' 1 . 0 ' ?> 

CDOCTYPE  chapter  SYSTEM  "/ just /a/test . dtd"  [ 
< ! ENTITY  plainEntity  "FOO  entity"> 

<! ENTITY  systemEntity  SYSTEM  "xmltest2 . xml "> 
]> 

<chapter> 

<TITLE>Title  SplainEntity ; </TITLE> 

<para> 

<inf ormaltable> 
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<tgroup  cols="3"> 

<tbody> 

<row><entry>al</ entryXentry  morerows=" 1 " >bl</ entry ><entry>cl</ entry ></row> 
<row><entry>a2</ entryXentry>c2< /entry  ></ row> 

<rowXentry>a3</ entryXentry>b3</ entryXentry>c3</ entryX/row> 

</tbody> 

</tgroup> 

</inf ormaltable> 

</para> 

SsystemEntity; 

<sectl  id="about"> 

<title>About  this  Document</title> 

<para> 

<! —  this  is  a  comment  — > 

<?php  print  'Hi!  This  is  PHP  version  ' . phpversion ( ) ;  ?> 

</para> 

</ sectl> 

</ chapter> 


Este  archivo  se  incluye  desde  xmltest .  xml: 

Ejemplo  5.  xmltest2.xml 

<?xml  version=" 1 . 0 " ?> 

< ! DOCTYPE  too  [ 

<!ENTITY  testEnt  "test  entity"> 

]> 

<f  oo> 

<element  attrib="value " /> 

StestEnt ; 

<?php  print  "This  is  some  more  PHP  code  being  executed.";  ?> 
</ f oo> 


1103 


XML 


xmlparserc  reate  (php  3>=  3.0.6,  php  4  >=  4.0.0) 


crea  un  analizador  de  XML 


int  xml_parser_create  ([string  encoding]) 


encoding  (opcional) 

Que  codification  de  caracteres  deberia  usar  el  analizador.  Las  siguientes  codification  de  caracteres 
estan  soportadas: 

ISO-8859-1  (pordefecto) 

US— ASCII 
UTF-8 

Esta  funcion  crea  un  analizador  XML  y  devuelve  un  rndice  para  usarlo  con  otras  funciones  XML. 
Devuelve  false  en  caso  de  fallo. 


xm  l_set_object  <php  4  >=  4 .0 .0) 

Usa  un  analizador  XML  dentro  de  un  objecto 

void  xml_set_ob ject  (int  parser,  object  &object ) 


Esta  funcion  hace  a  parser  utilizable  dentro  de  object.  Todas  las  funciones  de  callback  establecidas 
por  xml_set_element_handler\)  etc  se  asumen  como  metodos  de  object. 

<?php 

class  xml  { 
var  Sparser; 

function  xml ( )  { 

$this->parser  =  xml_parser_create ( ) ; 
xml_set_ob ject ( $this->parser ,  &$this)  ; 

xml_set_element_handler ( $this->parser , "tag_open", "tag_close") ; 
xml_set_character_data_handler ($this->parser,  "cdata")  ; 

} 

function  parse ($data)  { 

xml_parse ( $this->parser , $data) ; 

} 

function  tag_open ( Sparser , $tag, $attributes )  { 

var_dump (Sparser, Stag, Sattributes)  ; 

} 
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function  cdata ( Sparser , $cdata)  { 
var_dump (Sparser, $cdata) ; 

} 

function  tag_close ( Sparser ,  Stag)  { 
var_dump (Sparser,  Stag)  ; 

} 

}  / /  end  of  class  xml 
$xml_parser  =  new  xml ( ) ; 

$xml_parser->parse ("<A  ID=\ "hallo\ ">PHP</A>" ) ; 
?> 


Nota:  xml_set_object()  es  gestionable  a  partir  de  PHP  4.0. 


xml_set_element_handler  (php  3>=  3.0.6,  php  4  >=  4 .0  ,o> 

establece  gestores  de  los  elementos  principio  y  fin 

int  xml_set_element_handler  (int  parser,  string  startElementHandler ,  string 
endElement Handler) 


Establece  las  funciones  de  gestion  de  elementos  para  el  analizador  XML  parser. 
startElementHandler  y  endElementHandler  son  strings  que  contienen  los  nombres  de  las 
funciones  que  deben  existir  cuando  xml_parse')  es  llamado  por  parser. 

La  funcion  denominada  startElementHandler  debe  aceptar  tres  parametros: 

startElementHandler  (int  parser,  string  name,  string  attribs) 


parser 


El  primer  parametro,  parser,  es  una  referenda  al  analizador  XML  que  llama  al  gestor. 


name 

El  segundo  parametro,  name,  contiene  el  nombre  del  elemento  para  el  que  se  llama  a  este  gestor.  Si 
la  propiedad  de  case-folding  tiene  efecto  para  este  analizador,  el  nombre  del  elemento  estara  en 
mayusculas. 
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attribs 

El  tercer  parametro,  attribs,  contiene  un  array  asociativo  con  los  atributos  de  los  elementos  (si 
hay).  Las  claves  de  este  array  son  los  nombres  de  los  atributos,  los  valores  son  los  valores  de  los 
atributos.  Los  nombres  de  los  atributos  estan  en  mayusculas  (case-folded)  con  el  mismo  criterio  que 
los  nombres  de  los  elementos.  Los  valores  de  los  atributos  no  sufren  las  consecuencias  de 
case-folding. 

El  orden  original  de  los  atributos  se  puede  recuperar  recorriendo  attribs  del  modo  usual,  usando 
each').  La  primera  clave  del  array  es  el  el  primer  atributo,  y  asf  sucesivamente. 


La  funcion  llamada  endElement Handler  debe  aceptar  dos  parametros: 

endElementHandler  (int  parser,  string  name ) 


parser 


El  primer  parametro,  parser,  es  una  referenda  al  analizador  XML  que  llama  al  gestor. 


name 

El  segundo  parametro,  name,  contiene  el  nombre  del  elemento  para  el  que  se  llama  a  este  gestor.  Si 
la  propiedad  de  case-folding  tiene  efecto  para  este  analizador,  el  nombre  del  elemento  estara  en 
mayusculas. 


Si  una  funcion  gestora  se  establece  como  la  cadena  vacfa,  o  false,  el  gestor  en  cuestion  se  deshabilita. 
Se  devuelve  true  si  se  establecieron  los  gestores,  false  si  parser  no  es  un  analizador. 

En  la  actualidad  no  hay  soporte  para  gestores  objeto/metodo. 


xml_set_character  data  handler  (php 3>=  3.0.6,  php 4 >=  4.0.0 


Establece  gestores  de  datos  de  caracteres 


int  xml_set_character_data_handler  (int  parser,  string  handler) 


Establece  la  funcion  gestora  de  datos  de  caracteres  para  el  analizador  XML  parser,  handler  es  un 
string  que  contiene  el  nombre  de  la  funcion  que  debe  existir  cuando  xml_parse')  es  llamado  por 

parser. 

La  funcion  nombrada  en  handler  debe  aceptar  dos  parametros: 
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handler  (int  parser,  string  data) 


parser 


El  primer  parametro,  parser,  es  una  referencia  al  analizador  XML  que  llama  al  gestor. 


data 


El  segundo  parametro,  data,  contiene  los  datos  caracteres  como  string. 


Si  una  funcion  gestora  se  establece  como  la  cadena  vacla,  o  false,  el  gestor  en  cuestion  se  deshabilita. 
Se  devuelve  true  si  se  establecio  el  gestor,  false  si  parser  no  es  un  analizador. 

En  la  actualidad  no  hay  soporte  para  gestores  objeto/metodo. 


xml_set_processing_instruction_handler  (php  3>=  3.0.6,  php  4  >=  4 .0 ,0) 


Establece  el  gestor  de  instrucciones  de  procesado  (PI) 


int  xml_set_processing_instruction_handler  (int  parser,  string  handler ) 


Establece  ela  funcion  de  gestion  de  instrucciones  de  procesado  (PI)  para  el  analizador  XML  parser, 
handler  es  un  string  que  contiene  el  nombre  de  una  funcion  que  debe  existir  cuando  xml_parse  j  es 
llamada  por  parser. 

Una  instruccion  de  procedado  tiene  el  siguiente  formato: 

<? 

target 

datal> 


Puedes  poner  codigo  PHP  en  esa  etiqueta,  pero  ten  en  cuenta  una  limitacion:  en  una  PI  XML,  la  etiqueta 
de  fin  de  la  PI  (?>)  no  puede  ser  citada,  por  lo  que  esta  secuencia  de  caracteres  no  deberfa  aparecer  en  el 
codigo  PHP  que  insertes  con  las  Pis  en  documentos  XML.  Si  lo  hace,  el  resto  del  codigo  PHP,  as!  como 
la  etiqueta  de  fin  de  PI  "real",  seran  tratados  como  datos  de  caracteres. 

La  funcion  nombrada  en  handler  debe  aceptar  tres  parametros: 

handler  (int  parser,  string  target,  string  data) 
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parser 


El  primer  parametro,  parser,  es  una  referencia  al  analizador  XML  que  llama  al  gestor. 


target 


El  segundo  parametro,  target ,  contiene  el  objetivo  PI. 


data 


El  tercer  parametro,  data,  contiene  los  datos  PI. 


Si  una  funcion  gestora  se  establece  como  la  cadena  vacla,  o  false,  el  gestor  en  cuestion  se  deshabilita. 
Se  devuelve  true  si  se  establecio  el  gestor,  false  si  parser  no  es  un  analizador. 

En  la  actualidad  no  hay  soporte  para  gestores  objeto/metodo. 


xm  l_set_def  au  lt_hand  ler  (php  3>=  3.0.6,  php  4  >=  4 .0 .0) 


set  up  default  handler 


int  xml_set_default_handler  (int  parser,  string  handler) 


Establece  la  funcion  gestora  por  defecto  para  un  analizador  XML  parser,  handler  es  un  string  que 
contiene  el  nombre  de  la  funcion  que  debe  existir  cuando  xml_parse')  es  llamado  por  parser. 

La  funcion  nombrada  en  handler  debe  aceptar  dos  parametros: 

handler  (int  parser,  string  data ) 


parser 


El  primer  parametro,  parser,  es  una  referencia  al  analizador  XML  que  llama  al  gestor. 


data 

El  segundo  parametro,  data,  contiene  los  caracteres  de  dato.  Esto  puede  ser  la  declaracion  XML, 
la  declaracion  de  tipo  de  documento,  entidades  u  otros  datos  para  los  cuales  no  existe  otro  gestor. 


Si  una  funcion  gestora  se  establece  como  la  cadena  vacla,  o  false,  el  gestor  en  cuestion  se  deshabilita. 
Se  devuelve  true  si  se  establecio  el  gestor,  false  si  parser  no  es  un  analizador. 

En  la  actualidad  no  hay  soporte  para  gestores  objeto/metodo. 
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xml_set_unparsed_entity_decl_handler(PHP3>=  3  0  6  php4>=4oo) 

Establece  un  gestor  de  declaraciones  de  entidades  no  analizadas 

int  xml_set_unparsed_entity_decl_handler  (int  parser,  string  handler) 


Establece  la  funcion  gestora  de  declaration  de  entidades  no  analizadas  para  el  analizador  XML 
parser,  handler  es  una  cadena  que  contiene  el  nombre  de  una  funcion  que  debe  existir  cuando 
xml_parse ')  es  llamada  por  parser. 

Este  gestor  sera  llamado  si  el  analizador  XML  encuentra  una  declaracion  de  entidades  externas  con  una 
declaracion  NDATA,  como  la  siguiente: 

<! ENTITY  name  {publicld  |  systemld} 

NDATA  notationName> 


Mira  la  section  4.2.2  de  las  especificaciones  XML  1.0 

(http://www.w3.Org/TR/1998/REC-xml-19980210#sec-external-ent)  para  la  definition  de  entidades 
externas  de  notation  declarada. 

La  funcion  nombrada  en  handler  debe  aceptar  seis  parametros: 

handler  (int  parser,  string  entityName ,  string  base,  string  systemld,  string 
publicld,  string  notationName ) 


parser 


entityName 


base 


systemld 


El  primer  parametro,  parser,  es  una  referencia  al  analizador  XML  que  llama  al  gestor. 


El  nombre  de  la  entidad  que  va  a  ser  definida. 


Esta  es  la  base  para  resolver  el  identificador  de  sistema  ( systemld )  de  la  entidad  externa. 
Actualmente  este  parametro  siempre  sera  una  cadena  vatia. 


Identificador  de  Sistema  para  la  entidad  externa. 


publicld 


Identificador  publico  para  la  entidad  externa. 
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notationName 

Nombre  de  la  notation  de  esta  entidad  (ver  xml_set_notation_decl_handleti)). 

Si  una  funcion  gestora  se  establece  como  la  cadena  vatia,  o  false,  el  gestor  en  cuestion  se  deshabilita. 
Se  devuelve  true  si  se  establecio  el  gestor,  false  si  parser  no  es  un  analizador. 

En  la  actualidad  no  hay  soporte  para  gestores  objeto/metodo. 


xml_set_notation_decl  handler (php 3>=  3.0.6,  php 4 >=  4.0.0) 


Establece  gestores  de  declaraciones  de  notation 


int  xml_set_notation_decl_handler  (int  parser,  string  handler) 


Establece  las  funciones  gestoras  de  declaraciones  de  notation  para  el  analizador  XML  parser, 
handler  es  un  string  que  contiene  el  nombre  de  una  funcion  que  debe  existir  cuando  xml_parse')  es 
llamado  por  parser. 

Una  declaration  de  notation  es  parte  del  DTD  del  documento  y  tiene  el  siguiente  formato: 

<! NOTATION  name 
{ systemld  I  publicld } 

> 

Ver  la  section  4.7  de  las  especificaciones  XML  1.0 

(http://www.w3.Org/TR/1998/REC-xml-19980210#Notations)  para  la  definition  de  declaraciones  de 
notation. 

La  funcion  llamada  por  handler  debe  aceptar  cinco  parametros: 

handler  (int  parser,  string  notationName ,  string  base,  string  systemld, 
string  publicld) 


parser 

El  primer  parametro,  parser,  es  una  referenda  al  analizador  XML  que  llama  al  gestor. 

notationName 

Este  es  el  nombre  de  la  notation,  como  se  describio  arriba  en  el  formato  de  notation. 


base 

Esta  es  la  base  para  resolver  el  identificador  de  sistema  ( systemld )  de  la  declaration.  En  la 
actualidad  este  parametro  es  siempre  la  cadena  vatia. 
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systemld 


Identificador  de  sistema  de  la  declaration  de  notation  externa. 


publicld 


Identificador  publico  de  la  declaration  de  notacion  externa. 


Si  una  funcion  gestora  se  establece  como  la  cadena  vacfa,  o  false,  el  gestor  en  cuestion  se  deshabilita. 
Se  devuelve  true  si  se  establecio  el  gestor,  false  si  parser  no  es  un  analizador. 

En  la  actualidad  no  hay  soporte  para  gestores  objeto/metodo. 


xml_set_external_entity_ref_handler  (php  3>=  3.0.6,  php  4  >=  4.0.0) 


Establece  gestores  de  referencia  de  entidades  externas 


int  xml_set_external_entity_ref_handler  (int  parser,  string  handler) 


Establece  la  funcion  gestora  de  declarations  de  notacion  para  el  analizador  XML  parser,  handler 
es  un  string  que  contiene  el  nombre  de  una  funcion  que  debe  existir  cuando  xml_parse')  es  llamado  por 

parser. 

La  funcion  llamada  por  handler  debe  aceptar  cinco  parametros,  y  deberfa  devolver  un  valor  entero.  Si 
el  valor  devuelto  desde  el  gestor  (handler)  es  falso  (lo  cual  ocurrira  si  no  se  devuelve  un  valor),  el 
analizador  XML  dejara  de  analizar  y  xml_get_error_code ')  devolvera 

xml_error_external_entity_handling. 

int  handler  (int  parser,  string  openEntityNames ,  string  base,  string 
systemld,  string  publicld) 


parser 

El  primer  parametro,  parser,  es  una  referencia  al  analizador  XML  que  llama  al  gestor. 

openEntityNames 

El  segundo  parametro,  openEntityNames,  es  una  lista,  separada  por  espacios,  de  los  nombres 
de  las  entidades  que  se  abren  para  el  analisis  de  esta  entidad  (incluido  el  nombre  de  la  entidad 
referenciada). 


base 

Esta  es  la  base  para  resolver  el  identificador  de  sistema  ( systemid )  de  la  entidad  externa.  En  la 
actualidad  este  parametro  es  siempre  la  cadena  vacfa. 
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systemld 

El  cuarto  parametro,  systemld,  es  el  identificador  del  sistema  tal  como  se  especifico  en  la 
declaracion  de  la  entidad. 

publicld 

El  quinto  parametro,  publicld,  es  el  identificador  publico  como  se  especifico  en  la  declaracion 
de  la  entidad,  o  una  cadena  vacfa  si  no  se  especifico  ninguno;  el  espacio  en  bianco  en  el 
identificador  publico  se  habra  normalizado  como  se  requiere  en  las  especificaciones  XML. 


Si  una  funcion  gestora  se  establece  como  la  cadena  vacfa,  o  false,  el  gestor  en  cuestion  se  deshabilita. 
Se  devuelve  true  si  se  establecio  el  gestor,  false  si  parser  no  es  un  analizador. 

En  la  actualidad  no  hay  soporte  para  gestores  objeto/metodo. 


xmlparse  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 

comienza  a  analizar  un  documento  XML 


int  xml  parse  (int  parser,  string  data  [,  int  isFinal]) 


parser 


Una  referencia  al  analizador  XML  que  se  va  a  utilizar. 


data 

Conjunto  de  informacion  que  se  analizara.  Un  documento  puede  ser  analizado  por  trozos  llamando 
varias  veces  a  xml_parse()  con  nueva  informacion,  siempre  que  se  establezca  el  parametro 
isFinal  y  sea  true  cuando  el  ultimo  dato  sea  analizado. 

isFinal  (optional) 

Si  existe  y  es  true,  data  e s  el  ultimo  pedazo  de  informacion  envfado  en  este  analisis. 


Cuando  el  documento  XML  es  analizado,  se  hacen  llamadas  a  los  gestores  para  los  eventos  configurados 
tantas  veces  como  sea  necesario,  despues  de  que  esta  funcion  devuelva  true  o  false. 

Devuelve  true  si  el  analisis  se  realiza  con  exito,  false  si  no  tiene  exito,  o  si  parser  no  referencia  a 
un  analizador  valido.  Para  analisis  fallidos,  se  puede  recuperar  informacion  de  error  con 
xml_get_error_code\),  xml_error_string xml_get_current_line_numbei\), 
xml_get_current_column_number ')  y  x  m I _g e t_c u itc n t_b y te_i  n d c x ' ) . 
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xml_get_error_code  (php  3>=  3.0.6,  php  4  >=  4.0.0) 

obtiene  el  codigo  de  error  del  analizador  XML 

int  xml_get_error_code  (int  parser) 


parser 

Una  referenda  al  analizador  XML  del  que  obtener  el  codigo  de  error. 

Esta  funcion  devuelve  false  si  parser  no  referenda  un  analizador  valido,  o  si  no  devuelve  uno  de  los 
codigos  de  error  listados  en  la  section  de  codigos  de  error 

xmlerrorstring  (php  3>=  3.0.6,  php  4  >=  4.0.0 

obtiene  la  cadena  de  error  del  analizador  XML 

string  xml_error_string  (int  code ) 


code 

Un  codigo  de  error  de  xml_get_error_codeO- 

Devuelve  una  cadena  con  una  descripcion  textual  del  codigo  de  error  code,  o  false  si  no  se  encontro 
descripcion. 

xml_get_current  _line_number  (php  3>=  3.0.6,  php  4  >=  4.0.0) 

obtiene  el  numero  de  lrnea  actual  de  un  analizador  XML 

int  xml_get_current_line_number  (int  parser ) 
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parser 

Una  referenda  al  analizador  XML  del  que  obtener  el  numero  de  lfnea. 

Esta  funcion  devuelve  false  si  parser  no  referencia  un  analizador  valido,  o  si  no  devuelve  en  que 
lfnea  se  encuentra  actualmente  el  buffer  de  datos  del  analizador. 

xml_get_current_column_number  (php  3>=  3.0.6,  php  4  >=  4 .0 .0) 

Obtiene  el  numero  de  columna  actual  para  un  analizador  XML. 

int  xml_get_current_column_nuinber  (int  parser) 


parser 


Una  referencia  al  analizador  XML  del  que  obtener  el  numero  de  columna. 


Esta  funcion  devuelve  false  si  parser  no  referencia  un  analizador  valido,  o  si  no  devuelve  en  que 
columna  de  la  lfnea  actual  (como  se  obtiene  de  xml_get_current_line_number'))  en  la  que  se  encuentra 
el  analizador. 


xm  l_get_cu  rrent_byte  _i  ndex  <php  3>=  3.0.6,  php  4  >=  4.0.0) 

obtiene  el  fndice  del  byte  actual  para  un  analizador  XML 

int  xml_get_current_byte_index  (int  parser) 


parser 


Una  referencia  al  analizador  XML  del  que  obtener  el  fndice  del  byte. 


Esta  funcion  devuelve  false  si  parser  no  referencia  un  analizador  valido,  o  si  no  devuelve  en  que 
fndice  de  byte  se  encuentra  el  buffer  de  datos  del  analizador  (empezando  en  0). 
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xmlparserf  ree  (php  3>=  3.0.6,  php  4  >=  4 .0 .0 

Libera  un  analizador  XML 


string  xml  parser  free  (int  parser) 


parser 

Una  referencia  al  analizador  XML  que  se  liberara. 

Esta  funcion  devuelve  false  si  parser  no  referencia  un  analizador  valido,  o  si  no  libera  el  analizador 
y  devuelve  true. 

xml_parser_set_option  (php  3>=  3.0.6,  php  4  >=  4.0.0 

establece  las  opciones  de  un  analizador  XML 

int  xml  parser  set  option  (int  parser,  int  option,  mixed  value ) 


parser 


option 


value 


Una  referencia  al  analizador  XML  en  el  que  establecer  opciones. 


Opcion  que  se  establecera.  Ver  mas  abajo. 


El  nuevo  valor  de  la  opcion. 


Esta  funcion  devuelve  false  si  parser  no  referencia  un  analizador  valido,  o  si  la  opcion  no  pudo  ser 
establecida.  Si  no,  la  opcion  se  establece  y  devuelve  true. 

Las  opciones  siguientes  estan  disponibles: 


Tabla  1.  Opciones  de  analizador  XML 

Opcion  constante  Tipo  de  Datos 


Descripcion 
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Opcion  constante 

Tipo  de  Datos 

Descripcion 

XML_OPTION_CASE_FOLDIN( 

Integer 

Controla  si  case-folding  se 
habilita  para  este  analizador  XML. 
Habilitado  por  defecto. 

xml_option_target_enco 

Establece  que  codificacion 
destino  se  usa  en  este  analizador 
XML.  Por  defecto,  esta  puesta  al 
mismo  que  la  codificacion  fuente 
usada  por  xml_parser_createO. 

Las  codificaciones  de  destino 
soportadas  son  ISO-8859-1, 

US— ASCII y  UTF-8. 

xml_parser_get_option  (php  3>=  3.0.6,  php  4  >=  4.o.0) 

obtiene  las  opciones  de  un  analizador  XML 

mixed  xml  parser  get  option  (int  parser,  int  option) 


parser 


Una  referenda  al  analizador  XML  del  que  obtener  opciones. 


option 

Que  opcion  recuperar.  Ver  x m I _p a rs e r_s e t_o p t i o n ')  para  una  lista  de  opciones. 

Esta  funcion  devuelve  false  si  parser  no  referenda  un  analizador  valido,  o  si  la  opcion  no  pudo  ser 
establecida.  Si  no,  se  devuelve  la  opcion. 

Mirar  xml_parser_set_option  ')  para  la  lista  de  opciones. 


utf8_decode  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 

Convierte  una  cadena  codificada  UTF-8  a  ISO-8859- 1 

string  utf8_decode  (string  data) 
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Esta  funcion  decodificadata,  asume  codification  utf-8  ,  a  ISO-8859-1. 
Mira  utf8_encode ')  para  una  explication  de  codification  UTF-8. 


utf8_encode  (PHP  3>=  3.0.6,  PHP  4  >=  4.0.0) 
codifica  una  cadena  ISO-8859- 1  a  UTF-8 

string  utf8_encode  (string  data) 


Esta  funcion  codifica  la  cadena  data  a  utf-8,  y  devuelve  la  version  codificada.  utf-8  es  un 
mecanismo  estandar  usado  por  Unicodepara  codificar  valores  de  caracteres  amplios  en  un  chorro  de 
bytes,  utf-8  es  transparente  a  caracteres  de  ASCII  piano,  es  auto-sincronizado  (significa  que  es  posible 
para  un  programa  averiguar  donde  comienzan  los  caracteres  en  el  chorro  de  bytes)  y  se  puede  usar  con 
funciones  de  comparacion  de  cadenas  normales  para  ordenar  y  otros  fines.  PHP  codifica  caracteres 
utf-8  en  hasta  cuatro  bytes,  como  esto: 

Tabla  1.  Codification  UTF-8 


bytes 

bits 

representation 

1 

7 

Obbbbbbb 

2 

11 

1  lObbbbb  lObbbbbb 

3 

16 

lllObbbb  lObbbbbb  lObbbbbb 

4 

21 

llllObbb  lObbbbbb  lObbbbbb 

lObbbbbb 

Cada  b  representa  un  bit  que  puede  ser  usado  para  almacenar  datos  de  caracteres. 


1117 


LXXXIX.  XSLT  functions 


Aviso 

This  module  is  EXPERIMENTAL.  That  means,  that  the  behaviour  of  these 
functions,  these  function  names,  in  concreto  ANYTHING  documented  here  can 
change  in  a  future  release  of  PHP  WITHOUT  NOTICE.  Be  warned,  and  use  this 
module  at  your  own  risk. 


Introduction 

About  XSLT  and  Sablotron 

XSLT  (Extensible  Stylesheet  Language  (XSL)  Transformations)  is  a  language  for  transforming  XML 
documents  into  other  XML  documents.  It  is  a  standard  defined  by  The  World  Wide  Web  consortium 
(W3C).  Information  about  XSLT  and  related  technologies  can  be  found  at  http://www.w3.org/TR/xslt. 


Installation 

This  extension  uses  Sabloton  and  expat,  which  can  both  be  found  at  http://www.gingerall.com/.  Binaries 
are  provided  as  well  as  source. 

On  UNIX,  run  configure  with  the  — with-sablot  and  — enable-sablot-errors-descriptive 

options.  The  Sablotron  library  should  be  installed  somewhere  your  compiler  can  find  it. 


About  This  Extension 

This  PHP  extension  implements  support  Sablotron  from  Ginger  Alliance  in  PHP.  This  toolkit  lets  you 
transform  XML  documents  into  other  documents,  including  new  XML  documents,  but  also  into  HTML 
or  other  target  formats.  It  basically  provides  a  standardized  and  portable  template  mechanism,  separating 
content  and  design  of  a  website. 
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xslt_closelog  (php  4  >=  4.0.3) 

Clear  the  logfile  for  a  given  instance  of  Sablotron 

bool  xslt_closelog  (resource  xh) 


A  reference  to  the  XSLT  parser. 

This  function  returns  false  if  parser  does  not  refer  to  a  valid  parser,  or  if  the  closing  of  the  logfile 
fails.  Otherwise  it  returns  true. 


xslt_create  (PHP  4  >=  4.0.3) 

Create  a  new  XSL  processor. 

resource  xslt_create  () 


This  function  returns  a  handle  for  a  new  XSL  processor.  This  handle  is  needed  in  all  subsequent  calls  to 
XSL  functions. 


xslt_errnO(PHP4>=4  0  3) 

Return  the  current  error  number 

int  xslt_errno  (  [int  xh] ) 


Return  the  current  error  number  of  the  given  XSL  processor.  If  no  handle  is  given,  the  last  error  number 
that  occured  anywhere  is  returned. 


xslt_error(pHP4>=403) 

Return  the  current  error  string 
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mixed  xslt_error  ([ int  xh]) 


Return  the  current  error  string  of  the  given  XSL  processor.  If  no  handle  is  given,  the  last  error  string  that 
occured  anywhere  is  returned. 


xslt_fetch_resu  It  (php  4  >=  4.0.3) 

Fetch  a  (named)  result  buffer 

string  xslt_fetch_result  ([int  xh  string  result_name] ) 


Fetch  a  result  buffer  from  the  XSLT  processor  identified  by  the  given  handle.  If  no  result  name  is  given, 
the  buffer  named  "/_result"  is  fetched. 

xslt_free  (PHP  4  >=  4.0.3) 

Free  XSLT  processor 

void  xslt_free  ( resource  xh) 

Free  the  XSLT  processor  identified  by  the  given  handle. 

xslt_openlog  php  4  >=  4.0.3) 

Set  a  logfile  for  XSLT  processor  messages 

bool  xslt_openlog  ([resource  xh  string  logfile  int  loglevel]) 


Set  a  logfile  for  the  XSLT  processor  to  place  all  of  its  error  messages. 


xslt_output_begintransform  (PHP  4  >=  4.0.3) 

unknown 
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unknown  xslt_output_begintransform  ( unknown ) 


This  function  lacks  a  prototype  definition. 


xslt_output_endtransform  (php  4  >=  4.0.3) 

unknown 

unknown  xslt_output_endtransform  ( unknown ) 


This  function  lacks  a  prototype  definition. 


XSlt_OUtpUt_prOCeSS  (unknown) 

unknown 

unknown  xslt_process  ( unknown ) 


This  function  lacks  a  prototype  definition. 


xslt  run  (php 4 >=4.0.3) 


Apply  a  XSLT  stylesheet  to  a  file. 


bool  xslt_run  ([resource  xh  string  xslt_file  string  xml_data_file  string 
result  array  xslt_params  array  xslt_args] ] ] ) 


Process  the  xml_data_file  by  applying  the  xslt_file  stylesheet  to  it.  The  stylesheet  has  access  to 
xslt_params  and  the  processor  is  started  with  xslt_args.  The  result  of  the  XSLT  transformation  is  placed 
in  the  named  buffer  (default  is  "/_result"). 
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xslt_set_sax_handler  (php  4  >=  4.0.3) 

Set  SAX  handlers  for  a  XSLT  processor 

bool  xslt_set_sax_handler  ( resource  xh  array  handlers) 

Set  SAX  handlers  on  the  ressource  handle  given  by  xh. 

xslt_transform  <php  4  >=  4  0  3) 

unknown 

unknown  xslt_transform  ( unknown ) 

This  function  lacks  a  prototype  definition. 
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The  yaz()  functions  wrap  the  YAZ  API.  The  home  page  of  the  project  is  http://www.indexdata.dk/yaz/. 
Information  about  the  phpyaz  module  can  be  found  at  http://www.indexdata.dk/phpyaz/. 

PHP/YAZ  is  much  simpler  to  use  than  the  C  API  for  YAZ  but  less  flexible.  The  intent  is  to  make  it  easy 
to  build  basic  client  functions.  It  supports  persistent  stateless  connections  very  similar  to  those  offered  by 
the  various  SQL  APIs  that  are  available  for  PHP  This  means  that  sessions  are  stateless  but  shared 
amongst  users,  thus  saving  the  connect  and  INIT  steps  in  many  cases. 

Before  compiling  PHP  with  the  PHP/YAZ  module  you’ll  need  the  YAZ  toolkit.  Build  YAZ  and  install  it. 
Build  PHP  with  your  favourite  modules  and  add  option  — with-yaz.  Your  task  is  roughly  the  following: 

gunzip  -c  yaz-1 . 6 . tar . gz | tar  xf  - 
gunzip  -c  php-4 . 0 . X . tar . gz | tar  xf  - 
cd  yaz-1 . 6 

./configure  — prefix=/usr 
make 

make  install 
cd  . . / php-4 .O.X 

./configure  — with-yaz=/usr/bin 
make 

make  install 


PHP/YAZ  keeps  track  of  connections  with  targets  (Z-Associations).  A  positive  integer  represents  the  ID 
of  a  particular  association. 

The  script  below  demonstrates  the  parallel  searching  feature  of  the  API.  When  invoked  it  either  prints  a 
query  form  (if  no  arguments  are  supplied)  or  if  there  are  arguments  (term  and  one  or  more  hosts)  it 
searches  the  targets  in  array  host. 

Ejemplo  1.  YAZ() 

$num_hosts  =  count  ($host) ; 
if  (empty ($term)  | |  count ($host)  ==  0)  { 

echo  ' <form  method="get"> 

<input  type="checkbox" 

name="host [ ] "  value="bagel . indexdata . dk/gils"> 

GILS  test 

<input  type="checkbox" 

name="host [ ] "  value=" localhost : 9999/Default"> 
local  test 

<input  type="checkbox"  checked="l" 

name="host [ ] "  value="z3950 .bell-labs . com/books"> 

BELL  Labs  Library 

<br> 

RPN  Query: 

<input  type="text"  size="30"  name="term"> 

<input  type=" submit "  name="action"  value="Search"> 

r  . 

t 

}  else  { 
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echo  'You  searced  for  '  .  htmlspecialchars ( $term)  .  '<br>'; 

for  ($i  =  0;  $i  >  $num_hosts;  $i++)  { 

$ id [ ]  =  yaz_connect ( $host [ $i ] ) ; 
yaz_syntax ($id [$i] , "sutrs" ) ; 
yaz_search ( $id [ $i ] , " rpn" , $term) ; 

} 

yaz_wait ( ) ; 

for  ($i  =0;  $i  <  $num_hosts;  $i++)  { 

echo  ' <hr>'  .  $host[$i]  . 

$error  =  yaz_error ( $id [ $i ] ) ; 
if  (! empty ($error) )  { 

echo  "Error:  $error"; 

}  else  { 

$hits  =  yaz_hits ($id [ $ i ] ) ; 
echo  "Result  Count  $hits"; 

} 

echo  ' <dl>' ; 

for  ($p  =  1;  $p  <=  10;  $p++)  { 

$rec  =  yaz_record ($id [ $i ], $p,  "string" ) ; 
if  (empty ($rec) )  continue; 
echo  "<dt><b>$p</bx/dtxdd>"  ; 
echo  ereg_replace ( " \n" ,  "<br>\n" , $rec) ; 

echo  "</dd>"; 

} 

echo  ' </ dl>' ; 

} 

} 
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yazaddinfo  (php4) 

Returns  additional  error  information 

int  yaz_addinfo  (int  id) 


Returns  additional  error  message  for  target  (last  request).  An  empty  string  is  returned  if  last  operation 
was  a  success  or  if  no  additional  information  was  provided  by  the  target. 


yaz_close  (php4) 

Closes  a  YAZ  connection 

int  yaz_close  (int  id) 


Closes  a  connection  to  a  target.  The  application  can  no  longer  refer  to  the  target  with  the  given  id. 


yaz_connect  (PHP  4  ) 

Returns  a  positive  association  ID  on  success;  zero  on  failure 

int  yaz_connect  (string  zurl) 


yaz_connect()  prepares  for  a  connection  to  a  Z39.50  target.  The  zurl  argument  takes  the  form 
host[:port]  [/database].  If  port  is  omitted  210  is  used.  If  database  is  omitted  Default  is  used.  This  function 
is  non-blocking  and  doesn’t  attempt  to  establish  a  socket  -  it  merely  prepares  a  connect  to  be  performed 
later  when  yaz_wait')  is  called. 


yazerrno  (PHP  4) 

Returns  error  number 

int  yaz_errno  (int  id) 
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Returns  error  for  target  (last  request).  A  positive  value  is  returned  if  the  target  returned  a  diagnostic  code; 
a  value  of  zero  is  returned  if  no  errors  occurred  (success);  negative  value  is  returned  for  other  errors 
targets  didn’t  indicate  the  error  in  question. 

yaz_errno()  should  be  called  after  network  activity  for  each  target  -  (after  yaz_wait')  returns)  to 
determine  the  success  or  failure  of  the  last  operation  (e.g.  search). 


yaz_error  (PHP4) 

Returns  error  description 

int  yaz_error  (int  id) 

Returns  error  message  for  target  (last  request).  An  empty  string  is  returned  if  last  operation  was  a  success. 
yaz_error()  returns  a  english  message  corresponding  to  the  last  error  number  as  returned  by  yaz_errno ')• 

yaz_hitS(PHP4) 

Returns  number  of  hits  for  last  search 

int  yaz_hits  (int  id) 

yaz_hits()  returns  number  of  hits  for  last  search. 


yaz_range  (PHP  4  ) 

Specifies  the  maximum  number  of  records  to  retrieve 

int  yaz_range  (int  id,  int  start,  int  number) 

This  function  is  used  in  conjunction  with  yaz_search ')  to  specify  the  maximum  number  of  records  to 
retrieve  (number)  and  the  first  record  position  (start).  If  this  function  is  not  invoked  (only  yaz_search  ')) 
start  is  set  to  1  and  number  is  set  to  10. 

Returns  true  on  success;  false  on  error. 
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yazrecord  (php4) 

Returns  a  record 

int  yaz_record  (int  id,  int  pos,  string  type) 


Returns  record  at  position  or  empty  string  if  no  record  exists  at  given  position. 

The  yaz_record()  function  inspects  a  record  in  the  current  result  set  at  the  position  specified.  If  no 
database  record  exists  at  the  given  position  an  empty  string  is  returned.  The  argument,  type,  specifies  the 
form  of  the  returned  record.  If  type  is  "string"  the  record  is  returned  in  a  string  representation  suitable  for 
printing  (for  XML  and  SUTRS).  If  type  is  "array"  the  record  is  returned  as  an  array  representation  (for 
structured  records). 


yaz_search(PHP4) 

Prepares  for  a  search 

int  yaz_search  (int  id,  string  type,  string  query) 


yaz_search()  prepares  for  a  search  on  the  target  with  given  id.  The  type  represents  the  query  type  -  only 
"rpn"  is  supported  now  in  which  case  the  third  argument  is  a  prefix  notation  query  as  used  by  YAZ.  Like 
yaz_conncct  )  this  function  is  non-blocking  and  only  prepares  for  a  search  to  be  executed  later  when 
yaz_wait()  is  called. 


yaz_syntax  (PHP  4  ) 

Specifies  the  preferred  record  syntax  for  retrieval 

int  yaz_syntax  (int  id,  string  syntax) 


This  function  is  used  in  conjunction  with  yaz_search ')  to  specify  the  preferred  record  syntax  for  retrieval. 


yazwait  (PHP  4  ) 

Executes  queries 
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int  yaz_wait  (int  id,  string  syntax) 


This  function  carries  out  networked  (blocked)  activity  for  outstanding  requests  which  have  been  prepared 
by  the  functions  yaz_connect'),  yaz_search ').  yaz_wait()  returns  when  all  targets  have  either  completed 
all  requests  or  otherwise  completed  (in  case  of  errors). 
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NIS  (  anteriormente  llamado  Paginas  Amarillas  )  permite  la  administracion  de  red  de  los  archivos  de 
administracion  importantes  (e.g.El  archivo  de  contrasenas).  Para  mas  informacion  dirigirse  a  las  paginas 
de  ayuda  de  NIS  y  a  la  direccion.  Introduccion  a  YP/NIS 

(http://www.desy.de/~sieversm/ypdoku/ypdoku/ypdoku.html)  Hay  tambien  un  libro  llamado 
gestionando  NFS  Y  NIS  (http://www.oreilly.com/catalog/nfs/noframes.html)  por  Hal  Stern. 

Para  obtener  estas  funciones  de  trabajo,  usted  tiene  que  configure  PHP  con  —  con-  yp. 
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yp_get_default_domain  (php  3>=  3.0.7,  PHP  4  >=  4 .0 .0) 


Trae  el  valor  por  omision  de  dominios  de  maquina  NIS. 


int  yp  get_default_domain  (nulo) 


yp_  get_default_domain()  Retorna  el  valor  por  omision  del  dominio  del  nodo  o  FALSO.  Puede  ser 
usado  el  parametro  de  dominio  para  sucesivas  llamadas  a  NIS. 

Un  dominio  de  NIS  puede  ser  descrito  en  un  grupo  de  mapas  NIS.  Cada  host  necesita  buscar  uniones  de 
informacion  en  un  mismo  dominio.  Acudir  a  los  documentos  mencionados  en  el  comienzo  para  mas 
informacion. 


Ejemplo  1.  Ejemplo  para  el  dominio  por  omision 


Ver  tambien:  yp_  errno  (nombre  de  la  funcion)  y  yp_err_string  (nombre  de  la  funcion) 

yp_order  (PHP  3>=  3.0.7,  PHP  4  >=  4.0.0) 

Retorna  el  numero  de  orden  para  el  mapa. 

int  yp_  order  (nombre  de  la  funcion)  (cadena  dominio,  cadena  mapa ) 

yp_  order(nombre  de  la  funcion)()  Retorna  el  numero  de  orden  para  un  mapa  o  FALSO. 

Ejemplo  1.  Ejemplo  para  ordenar  el  NIS 


Ver  tambien:  yp  get_default_domain  yp_errno  yp_err_string 
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yp_master  (PHP  3>=  3.0.7,  PHP  4  >=  4.0.0) 

Retorna  el  nombre  del  servidor  de  NIS  maestro  para  el  mapa. 

cadena  yp_master  (cadena  dominio,  cadena  mapa) 

yp_master()  Retorna  el  nombre  de  maquina  del  servidor  de  NIS  maestro  para  un  mapa. 

Ejemplo  1.  Ejemplo  para  el  NIS  domina 


Ver  tambien:  yp_get_default_domain(nombre  de  la  funcion)  yp_errno(nombre  de  la  funcion)  y 
yp_err_string(nombre  de  la  funcion) 

yp_match  (PHP  3>=  3.0.7,  PHP  4  >=  4.0.0) 

Retorna  la  linea  companera  (pareja). 

cadena  yp  match  (cadena  dominio,  cadena  mapa,  cadena  teclea) 

yp_match(nombre  de  la  funcion)()  Retorna  el  valor  asociado  con  la  Have  pasada  fuera  del  mapa 
especificado  o  FALSO.  esta  Have  tiene  que  ser  exacta. 

Ejemplo  1.  Ejemplo  para  NIS  parejo 

En  este  caso  esto  puede  ser:  Joe:##joe:lllll:100:joe  usuario:/hogar/j/joe:  User:/usr/local/bin/bash 
Ver  tambien:  yp_get_default_domain  yp_errno  y  yp_err_string 

yp_first  (unknown) 

devuelve  la  primera  clave  emparejada  con  el  nombrado  mapa. 
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string[]  yp_first  (catena  dominio,  cadena  mapa) 

yp_first(nombre  de  la  funcion)()  Retorna  la  primera  clave  de  valor  pareada  del  mapa  nombrado  en  el 
dominio,  de  otra  manera  FALSO. 

Ejemplo  1.  Ejemplo  para  el  primer  NIS 


Ver  tambien:  yp_get_default_domain  yp_errno  y  yp_err_string 

yp_next  (PHP  3>=  3.0.7,  PHP  4  >=  4.0.0) 

Devuelve  la  siguiente  clave  tecleada  en  el  nombre  de  mapa 

string!]  yp_next  (cadena  dominio,  cadena  mapa,  cadena  teclea) 

yp_next()  devuelve  el  siguiente  par  de  valor  tecleado  en  el  mapa  de  nombres  despues  de  la  clave 
especificada  o  FALSO. 

Ejemplo  1.  Ejemplo  para  NIS  siguiente 


Ver  tambien:  yp_get_default_domain  yp_errno  y  yp_err_string 

yp_errno  (PHP  4  >=  4.0.6) 

Retorna  el  codigo  de  error  de  la  operacion  previa. 

int  yp_errno  () 

yp_errno()  retorna  el  codigo  de  error  de  la  operacion  previa. 
Los  errores  posibles  son: 
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1  args  para  funcionar  son  malos 

2  fallo  de  RPC-  dominio  ha  sido  unbound 

3  no  puede  unir  a  servidor  en  este  dominio 

4  ningun  tal  mapa  en  dominio  de  servidor 

5  ninguna  tal  Have  en 

6  interno  yp  error  de  cliente  o  servidor 

7  fallo  de  asignacion  de  recurso 

8  ningunos  mas  registros  en  base  de  datos  de  mapa 

9  no  puede  comunicar  wiTh  portmapper 

10  no  puede  comunicar  con  ypbind 

1 1  no  puede  comunicar  con  ypserv 

12  nombre  de  dominio  local  no  conjunto 

13  yp  base  de  datos  es  malo 

14  yp  La  version  mismatch 

15  violacion  de  acceso 

16  base  de  datos  ocupar 

Ver  tambien:  yp_err_string 


yp_err_string  (PHP  4  >=  4.0.6) 

devuelve  el  mensaje  de  error  asociado  con  la  operacion  previa.Util  que  indica  el  problema  exacto. 

cadena  yp_err_string  (nulo) 


yp_err_string()  Retorna  el  mensaje  de  error  asociado  con  la  operacion  previa.Util  para  indicar  que  salio 
mal  exactamente. 

Ejemplo  1.  Ejemplo  para  errores  de  NIS 


Vea  tambien:  yp  errno 
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XCII.  Zip  File  Functions  (Read  Only  Access) 

This  module  uses  the  functions  of  the  ZZIPlib  (http://zziplib.sourceforge.net/)  library  by  Guido  Draheim 
to  transparently  read  ZIP  compressed  archives  and  the  hies  inside  them. 

Please  note  that  ZZIPlib  only  provides  a  subset  of  functions  provided  in  a  full  implementation  of  the  ZIP 
compression  algorithm  and  can  only  read  ZIP  hie  archives.  A  normal  ZIP  utility  is  needed  to  create  the 
ZIP  hie  archives  read  by  this  library. 

Zip  support  in  PHP  is  not  enabled  by  default.  You  will  need  to  use  the  — with-zip  conhguration  option 
when  compiling  PHP  to  enable  zip  support.  This  module  requires  ZZIPlib  version  >=  0.10.6. 

Nota:  Zip  support  before  PHP  4.1 .0  is  experimental.  This  section  reflects  the  Zip  extension  as  it 
exists  in  PHP  4.1.0  and  later. 


Example  Usage 

This  example  opens  a  ZIP  hie  archive,  reads  each  hie  in  the  archive  and  prints  out  its  contents.  The 
test2.zip  archive  used  in  this  example  is  one  of  the  test  archives  in  the  ZZIPlib  source  distribution. 

Ejemplo  1.  Zip  Usage  Example 

<?php 

$zip  =  zip_open ( " /tmp/test2 . zip" ) ; 
if  ($zip)  { 

while  ($zip_entry  =  zip_read ( $zip) )  { 

echo  "Name:  "  .  zip_entry_name ($zip_entry)  .  "\n"; 

echo  "Actual  Filesize:  "  .  zip_entry_f ilesize ($zip_entry)  .  "\n"; 

echo  "Compressed  Size:  "  .  zip_entry_compressedsize ( $zip_entry)  .  "\n"; 

echo  "Compression  Method:  "  .  zip_entry_compressionmethod ($zip_entry)  .  "\n" 

if  ( zip_entry_open ( $  zip,  $zip_entry,  "r"))  { 

echo  "File  Contents : \n" ; 

$buf  =  zip_entry_read ($zip_entry,  zip_entry_f ilesize ($zip_entry) ) ; 
echo  "$buf\n"; 

zip_entry_close ($zip_entry) ; 

} 

echo  "\n"; 


} 

zip_close ($zip) ; 


} 
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?> 
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zip_close  (PHP  4  >=  4.0.7RC1) 

Close  a  Zip  File  Archive 

void  zip_close  (resource  zip) 

Closes  a  zip  file  archive.  The  parameter  zip  must  be  a  zip  archive  previously  opened  by  zip_open '). 
This  function  has  no  return  value. 

See  also  zip_openO  and  zip  read'j. 


zipentryclose  (php  4  >=  4 .0 .7rcu 

Close  a  Directory  Entry 

void  zip_entry_close  (resource  zip_entry) 


Closes  a  directory  entry  specified  by  zip_entry.  The  parameter  zip_entry  must  be  a  valid 
directory  entry  opened  by  zip_entry_open  '). 

This  function  has  no  return  value. 

See  also  zip_entry_opcn ')  and  zip_entry_read {). 


zipentrycompressedsize  <php  4  >=  4.o.7rci) 

Retrieve  the  Compressed  Size  of  a  Directory  Entry 

int  zip_entry_compressedsize  (resource  zip_entry) 

Returns  the  compressed  size  of  the  directory  entry  specified  by  zip_entry.  The  parameter 
zip_entry  is  a  valid  directory  entry  returned  by  zip_readQ- 

See  also  zip_open')  and  zip  read  ). 
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zipentrycompressionmethod  (php  4  >=  4.o.7rci) 

Retrieve  the  Compression  Method  of  a  Directory  Entry 

string  zip_entry_compressionmethod  (resource  zip_entry) 

Returns  the  compression  method  of  the  directory  entry  specified  by  zip_entry.  The  parameter 
zip_entry  is  a  valid  directory  entry  returned  by  zipread). 

See  also  zip_open  )  and  zip  read'). 

zipentryf  ilesize  (php  4  >=  4 .0  .7rcd 

Retrieve  the  Actual  File  Size  of  a  Directory  Entry 

int  zip_entry_f ilesize  (resource  zip_entry) 

Returns  the  actual  size  of  the  directory  entry  specified  by  zip_entry.  The  parameter  zip_entry  is 
a  valid  directory  entry  returned  by  zip  readQ. 

See  also  zip_open  )  and  zip  read'). 

zip  entry  name  (PHP  4  >=  4.0.7RC1) 

Retrieve  the  Name  of  a  Directory  Entry 

string  zip_entry_name  (resource  zip_entry) 

Returns  the  name  of  the  directory  entry  specified  by  zip_entry.  The  parameter  zip_entry  is  a 
valid  directory  entry  returned  by  zip_read'). 

See  also  zipopcn ')  and  zip  read  ). 

zip_entry_open  (PHP  4  >=  4.0.7RC1) 

Open  a  Directory  Entry  for  Reading 
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bool  zip_entry_open  (resource  zip,  resource  zip_entry  [,  string  mode]) 


Opens  a  directory  entry  in  a  zip  file  for  reading.  The  parameter  zip  is  a  valid  resource  handle  returned 
by  zipopen ').  The  parameter  zip_entry  is  a  directory  entry  resource  returned  by  zip  read').  The 
optional  parameter  mode  can  be  any  of  the  modes  specified  in  the  documentaion  for  fopen'). 

Nota:  Currently,  mode  is  ignored  and  is  always  "rb".  This  is  due  to  the  fact  that  zip  support  in  PHP  is 
read  only  access.  Please  see  fopen  [)  for  an  explanation  of  various  modes,  including  "rb". 


Returns  true  on  succes  or  false  on  failure. 

Nota:  Unlike  fopen  [)  and  other  similar  functions,  the  return  value  of  zip_entry_open()  only  indicates 
the  result  of  the  operation  and  is  not  needed  for  reading  or  closing  the  directory  entry. 


See  also  zip_entry_readQ  and  zip_entry_close  ). 


zipentryread  (php  4  >=  4.o.7rci) 


Read  From  an  Open  Directory  Entry 


string  zip_entry_read  (resource  zip_entry  [,  int  length]) 


Reads  up  to  length  bytes  from  an  open  directory  entry.  If  length  is  not  specified,  then 
zip_entry_read()  will  attempt  to  read  1024  bytes.  The  parameter  zip_entry  is  a  valid  directory  entry 
returned  by  zip  read '). 

Nota:  The  length  parameter  should  be  the  uncompressed  length  you  wish  to  read. 


Returns  the  data  read,  or  false  if  the  end  of  the  file  is  reached. 

See  also  zip_entry_openO,  zip_entry_close ')  and  zip_entry_filesizeO- 


zip_open  (PHP  4  >=  4.0.7RC1) 


Open  a  Zip  File  Archive 


resource  zip_open  (string  filename) 
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Opens  a  new  zip  archive  for  reading.  The  filename  parameter  is  the  filename  of  the  zip  archive  to 
open. 

Returns  a  resource  handle  for  later  use  with  zip_read')  and  zip_close ')  or  returns  false  if  filename 
does  not  exist. 

See  also  zip  read ')  and  zip_close')- 


zip_read  (PHP  4  >=  4.0.7RC1) 

Read  Next  Entry  in  a  Zip  File  Archive 

resource  zip_read  (resource  zip) 


Reads  the  next  entry  in  a  zip  file  archive.  The  parameter  zip  must  be  a  zip  archive  previously  opened  by 
zip_open '). 

Returns  a  directory  entry  resource  for  later  use  with  the  zip_entry_...()  functions. 

See  also  zip_open'),  zip_close'),  zip_entry_open),  and  zip  entry  read '). 
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XCIII.  Funciones  de  Compresion 

Este  modulo  usa  la  funcion  de  zlib  (http://www.gzip.org/zlib/)  de  Jean-loup  Gailly  y  Mark  Adler  para 
leer  y  grabar  archivos  comprimidos  .gz,  de  un  modo  transparente.  Con  este  modulo,  es  requisito  usar  una 
version  de  zlib  igual  o  posterior  a  1.0.9. 

Este  modulo  contiene  versiones  de  la  mayorfa  de  las  funciones  de  Sistema  de  archivos  que  funcionan  con 
los  archivos  comprimidos  con  gzip  (y  con  los  no-comprimidos  tambien,  pero  no  con  conectores 
(sockets)). 


Pequeno  codigo  de  ejemlo 

Abre  un  archivo  temporal  y  escribe  en  el,  una  cadena  de  prueba,  y  luego  presenta  el  cotenido  del  archivo 
dos  veces 

Ejemplo  1.  Ejemplo  de  Zlib 

<?php 

$filename  =  tempnam ( ' /tmp' ,  ' zlibtest'  )  . '  . gz'  ; 
print  " <html>\n<head></head>\n<body>\n<pre>\n" ; 

$s  =  "Solo  es  una  prueba,  prueba,  prueba, prueba,  prueba,  prueba !\n"; 

/ /  Abre  el  archivo  para  escribirlo  con  maximo  de  compresion 
$zp  =  gzopen ($filename,  "w9"); 

//  Escribe  la  cadena  en  el 
gzwrite($zp,  $s); 

//  Cierra  el  fichero 
gzclose ($zp) ; 

/ /  Abre  el  fichero  para  lectura 
$zp  =  gzopen ($filename,  "r"); 

//  Lee  3  caracteres 
print  gzread($zp,  3); 

//  Salida  hasta  el  final  del  fichero,  para  cerrarlo  luego. 
gzpassthru ($zp) ; 
print  "\n"; 

//  Abre  el  fichero  y  muestra  su  contenido  (por  segunda  vez) . 
if  (readgzfile ($filename)  !=  strlen ($s) )  { 

echo  "Error  con  las  funciones  zlib!"; 

} 

unlink ( $f ilename ) ; 

print  "  <pre>\n</hlx/body>\n</html>\n" ; 
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Zlib 


cierra  un  puntero  a  archivo-gz  abierto 

int  gzclose  (int  zp) 

El  archivo-gz  al  que  apunta  zp  se  cierra. 

Devuelve  true  (verdadero)  si  fue  exitoso,  si  hubo  errores  devuelve  false. 

El  puntero  al  archivo-gz  debe  ser  valido  y  debe  apuntar  a  un  archivo  correctamente  abierto  con  gzopcn  '). 


gzeof  (PHP  3,  PHP  4  >=  4.0.0) 

prueba  el  fin-de-archivo  de  un  puntero  de  archivo-gz 

int  gzeof  (int  zp) 


Devuelve  verdadero  si  el  puntero-a-archivo  esta  en  el  fin-de-archivo,  o  ha  ocurrido  un  error.  De  otro 
modo  devuelve  falso. 

El  puntero  al  archivo-gz  debe  ser  valido  y  debe  apuntar  a  un  archivo  correctamente  abierto  con  gzopenQ. 


gzfile  (PHP  3,  PHP  4  >=  4.0.0) 

lee  el  archivo  gz  completo  en  un  arreglo 

array  gzfile  (string  nombre_archivo  [,  int  usar_include_path] ) 

Identico  a  readgzfile  3,  solo  que  gzfile()  devuelve  el  fichero  en  un  arreglo. 

Se  puede  usar  el  segundo  parametro  opcional  poniendolo  a  "1",  si  se  quiere  que  la  funcion  busque 
tambien  el  archivo  en  la  trayectoria  definida  como  include_path. 

Vea  tambien  readgzfile  ),  y  gzopen)). 
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Zlib 


toma  caracteres  de  un  archivo-gz 

cadena  gzgetc  (int  zp) 


Devuelve  una  cadena  conteniendo  un  caracter  en  particular  (sin  comprimir)  lefdo  del  archivo  al  que 
apunta  zp.  Devuelve  false  cuando  esta  al  final  del  archivo  (al  igual  que  gzeof')). 

El  puntero  al  archivo-gz  debe  ser  valido  y  debe  apuntar  a  un  archivo  correctamente  abierto  con  gzopen)). 
Vea  tambien  gzopen  '),  y  gzgets '). 


gzgets  (PHP  3,  PHP  4  >=4.0.0) 

toma  una  linea  del  archivo  apuntado 

string  gzgets  (int  zp,  int  longitud) 


Devuelve  una  cadena  (descomprimida)  con  longitud  -  1  bytes  de  largo,  lefda  del  archivo  apuntado  por  fp. 
La  lectura  finaliza  cuando  se  han  lefdo  longitud  -  1  bytes,  ante  un  salto  de  linea  o  un  fin-de-archivo  (lo 
que  ocurra  primero). 

Si  ocurre  un  error,  devuelve  falso. 

El  puntero  al  archivo-gz  debe  ser  valido  y  debe  apuntar  a  un  archivo  correctamente  abierto  con  gzopen)). 
Vea  tambien  gzopen  '),  gzgetc)),  y  fgets)). 


gzgetss  (PHP  3,  PHP  4  >=4.0.0) 

toma  una  linea  del  archivo-gz  apuntado  y  le  quita  los  tags  HTML 

string  gzgetss  (int  zp,  int  longitud  [,  string  tags_permitidos] ) 

Identica  a  gzgets )),  excepto  que  gzgetss  intenta  quitar  cualquier  "tag"  HTML  o  PHP  del  texto  que  lee. 
Se  puede  usar  el  tercer  parametro  para  indicar  que  parametros  no  deben  ser  extrafdos. 

Nota:  tags_permitidos  fue  agregado  en  la  version  de  PHP  3.0.13,  PHP4B3. 
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Vease  tambien  gzgets'),  gzopen)),  y  strip_tags'). 


gzopen  (PHP  3,  PHP  4  >=  4.0.0) 


open  gz-file 


int  gzopen  (string  nombre_fichero,  string  modo  [,  int  use_include_path] ) 


Abre  un  archivo  gzip  (.gz)  para  lectura  o  escritura.  El  parametro  modo  es,  como  en  fopenQ  ("rb"  o  "wb") 
pero  puede  incluir  tambien  el  nivel  de  compresion  ("wb9")  o  la  estrategia:  T  para  filtrado  de  datos  como 
en  "wb6f,  ’h’  para  comprimir  solo  por  Huffman  igual  que  en  "wblh".  (Ver  la  description  de  deflatelnit2 
en  zlib.h  para  mas  information  sobre  el  parametro  de  estrategia.) 

Gzopen  puede  usarse  para  leer  o  escribir  un  fichero  que  no  este  en  formato  gzip;  en  ese  caso  gzread)) 
leera  el  archivo  directamente,  sin  descomprimirlo. 

Gzopen  devuelve  un  puntero  al  archivo  abierto  y  luego,  cualquier  proceso  de  lectura  o  escritura 
relacionado  con  ese  descriptor  de  archivo,  sera  transparente:  se  comprimira  o  descomprimira  los  datos 
segun  la  necesidad,  de  manera  automatica. 

Si  la  apertura  fallase,  se  devolvera  falso. 

Se  puede  usar  el  tercer  parametro  opcional,  poniendolo  a  "1",  si  se  quiere  buscar  tambien  el  fichero  en  la 
trayectoria  include_path 


Ejemplo  1.  ejemplo  de  gzopen() 

$fp  =  gzopen (" /tmp/file . gz " ,  "r"); 


Vea  tambien  gzclose )). 


gzpassthru  (PHP  3,  PHP  4  >=4.0.0) 

Devuelve  el  remanente  de  datos  de  un  fichero-gz 

int  gzpassthru  (int  zp) 


Lee  hasta  el  Fin-De-Archivo  del  archivo  gz  dado,  y  escribe  los  resultados  (descomprimidos)  en  la  salida 
standard. 
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Si  ocurre  un  error,  devuelve  Falso. 

El  puntero  al  archivo-gz  debe  ser  valido  y  debe  apuntar  a  un  archivo  correctamente  abierto  con  gzopcn '). 
El  archivo-gz  es  cerrado  cuando  gzpassthru()  termina  de  leerlo  (dejando  zp  sin  utilidad). 


gzputs  (PHP  3,  PHP  4  >=  4.0.0) 

escribe  al  fichero-gz  que  se  apunta 

int  gzputs  (int  zp,  string  str  [,  int  longitud ]) 


gzputsQ  es  un  alias  a  gzwrite '),  y  es  absolutamente  identico. 


gzread  (PHP  3,  PHP  4  >=  4.0.0) 

Lee  archivos-gz  en  modo  Binario 

string  gzread  (int  zp,  int  longitud) 


gzread()  lee  hasta  longitud  bytes  del  archivo-gz  apuntado  por  el  parametro  zp.  La  lectura  termina 
cuando  se  han  lefdo  longitud  bytes  (descomprimidos)  o  se  alcanza  el  fin-de-archivo,  lo  que  sucediera 
primero. 


//  Pone  los  contenidos  del  gz,  a  una  cadena 
$filename  =  " /usr/local/algo . txt . gz " ; 

$zd  =  gzopen  (  $filename,  "r"  ); 

$contents  =  gzread(  $zd,  10000  ); 
gzclose  (  $zd  ) ; 


Ver  tambien  gzwriteQ,  gzopen 3,  gzgetsO,  gzgetss)),  gzhleQ,  y  gzpassthru(). 


gzrewind  (PHP  3,  PHP  4  >=4.0.0) 


Reposiciona  al  puntero  de  archivo-gz,  al  inicio  de  aquel 
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int  gzrewind  (int  zp) 


Reubica  el  indicador  de  posicion  del  archivo,  al  comienzo  del  mismo. 
si  surge  un  error,  devuelve  0. 

El  puntero  al  archivo-gz  debe  ser  valido  y  debe  apuntar  a  un  archivo  correctamente  abierto  con  gzopen)). 
Ver  tambien:  gzseek))  y  gztell )). 


gzseek 


(PHP  3,  PHP  4  >=  4.0.0) 


Posiciona  el  puntero  del  archivo-gz 


int  gzseek  (int  zp,  int  offset ) 


Busca  la  posicion  dentro  del  archivo  zp,  indicada  en  bytes  por  el  parametro  de  desplazamiento  offset.  Es 
equivalente  a  llamar  (en  C)  gzseek  (  zp,  offset,  SEEK_SET  ). 

Si  el  archivo  se  abre  para  lectura,  la  funcion  sera  emulada,  pero  puede  ponerse  extremadamente  lenta.  Si 
se  trata  de  escritura,  solo  esta  soportada  la  busqueda  hacia  adelante;  gzseek  comprime  entonces  una 
secuencia  de  ceros  hasta  que  alcanza  la  nueva  ubicacion. 

Si  se  completa  el  pedido  con  exito,  devuelve  0;  de  lo  contrario,  devuelve  -1.  Note  que  la  busqueda  mas 
alia  del  fin-de-archivo  no  se  considera  un  error. 

Vea  tambien  gztell  3  y  gzrewind)). 


gztell  (PHP  3,  PHP  4  >=  4.0.0) 

Indica  la  posicion  de  lecto-escritura  en  el  archivo 

int  gztell  (int  zp) 


Devuelve  la  posicion  dentro  del  hchero  referido  por  zp;  p.e.,  su  desplazamiento  en  el  cuerpo  del  archivo. 
Si  hay  algun  error,  devuelve  falso. 

El  puntero  al  archivo-gz  debe  ser  valido  y  debe  apuntar  a  un  archivo  correctamente  abierto  con  gzopen)). 
Ver  tambien  gzopen )),  gzseek))  y  gzrewind)). 
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Zlib 


Escritura  de  ficheros  gz  en  modo  Binario 

int  gzwrite  (int  zp,  string  cadena  [,  int  largo]) 


gzwrite()  escribe  el  contenido  de  cadena  al  fichero  gz  referido  por  zp.  Si  el  parametro  largo  esta 
presente,  se  detendra  la  escritura  luego  de  escribir  largo  bytes  (descomprimidos)  o  al  llegar  el  final  de 
la  cadena,  lo  que  ocurriese  primero. 

Note  que  si  se  pasa  el  argumento  largo,  la  opcion  magic_quotes_runtime  sera  ignorada  y  no  se 
quitaran  barras  de  la  cadena  en  cuestion. 

Ver  tambien  gzread'),  gzopcn '),  y  gzputs '). 


readgzfile  (PHP  3,  PHP  4  >=4.0.0) 


devuelve  el  fichero-gz 


int  readgzfile  (string  nombre_archivo 


int  usar_trayectoria_include ]  ) 


Lee  el  archivo,  lo  descomprime  y  lo  escribe  en  la  salida  estandar. 

Readgzfile!)  puede  usarse  para  leer  un  archivo  comprimido  o  no  con  gzip;  en  cuyo  caso  readgzfile()  leera 
directamente  el  archivo,  sin  descomprimirlo. 

Devuelve  el  numero  de  bytes  (descomprimidos)  lefdos  del  archivo,  si  ocurre  un  error,  se  devuelve  falso  y 
hasta  que  se  llame  como  @readgzfile,  se  imprime  un  mensaje  de  error. 

El  archivo  nombre_archivo  se  abrira  en  el  sistema  de  archivos  y  su  contenido  enviado  a  la  salida 
estandar. 

Puede  usarse  el  segundo  paametro  opcional  dandole  el  valor  "1",  si  se  quiere  que  se  busque  el  archivo 
tambien  dentro  de  la  trayectoria  "include":  include_path 

Ver  tambien  gzpassthru  ),  gz.fi  le),  y  gzopcn '). 
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PEAR  is  dedicated  to  Malin  Bakken,  born  1999-11-21  (the  first  PEAR  code  was  written  just  two  hours 
before  she  was  born). 


What  is  PEAR? 

PEAR  is  a  code  repository  for  PHP  extensions  and  PHP  library  code  inspired  by  TeX’s  CTAN  and  Perl’s 
CPAN. 

The  purpose  of  PEAR  is: 

•  to  provide  a  consistent  means  for  library  code  authors  to  share  their  code  with  other  developers 

•  to  give  the  PHP  community  an  infrastructure  for  sharing  code 

•  to  define  standards  that  help  developers  write  portable  and  reusable  code 

•  to  provide  tools  for  code  maintenance  and  distribution 
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Nota:  The  PEAR  Coding  Standards  applies  to  code  that  is  to  become  a  part  of  PEAR,  either 
distributed  with  PHP  or  available  for  download  via  PEAR’s  install  tool. 


Indenting 

Use  an  indent  of  4  spaces,  with  no  tabs.  If  you  use  Emacs  to  edit  PEAR  code,  you  should  set 
indent-tabs-mode  to  nil.  Here  is  an  example  mode  hook  that  will  set  up  Emacs  according  to  these 
guidelines  (you  will  need  to  ensure  that  it  is  called  when  you  are  editing  PHP  files): 

(defun  php-mode-hook  () 

(setq  tab-width  4 

c-basic-of f set  4 
c-hanging-comment-ender-p  nil 
indent-tabs-mode 
(not 

(and  (string-match  " /\ \ (PEAR\\ | pearW) / "  (buffer-file-name)) 
(string-match  "\.php$"  (buffer-file-name)))))) 


Here  are  vim  rules  for  the  same  thing: 

set  expandtab 
set  shiftwidth=4 
set  tabstop=4 


Control  Structures 


These  include  if,  for,  while,  switch,  etc.  Here  is  an  example  if  statement,  since  it  is  the  most  complicated 
of  them: 

if  ( (conditionl )  ||  (condition2 ) )  { 

actionl ; 

}  elseif  ((condition3)  &&  (condition4 ) )  { 

action2 ; 

}  else  { 

default act ion; 

} 


Control  statements  should  have  one  space  between  the  control  keyword  and  opening  parenthesis,  to 
distinguish  them  from  function  calls. 

You  are  strongly  encouraged  to  always  use  curly  braces  even  in  situations  where  they  are  technically 
optional.  Having  them  increases  readability  and  decreases  the  likelihood  of  logic  errors  being  introduced 
when  new  lines  are  added. 
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For  switch  statements: 

switch  (condition)  { 

case  1  : 

actionl ; 
break; 

case  2  : 

action2 ; 
break; 

default : 

def aul tact ion; 
break; 


} 


Function  Calls 


Functions  should  be  called  with  no  spaces  between  the  function  name,  the  opening  parenthesis,  and  the 
first  parameter;  spaces  between  commas  and  each  parameter,  and  no  space  between  the  last  parameter, 
the  closing  parenthesis,  and  the  semicolon.  Here’s  an  example: 

$var  =  foo($bar,  $baz,  $quux) ; 


As  displayed  above,  there  should  be  one  space  on  either  side  of  an  equals  sign  used  to  assign  the  return 
value  of  a  function  to  a  variable.  In  the  case  of  a  block  of  related  assignments,  more  space  may  be 
inserted  to  promote  readability: 

$short  =  foo($bar); 

$long_variable  =  foo($baz); 


Function  Definitions 

Function  declaractions  follow  the  "one  true  brace"  convention: 

function  fooFunction ($argl,  $arg2  =  ") 

{ 

if  (condition)  { 
statement ; 

} 

return  $val; 

} 
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Arguments  with  default  values  go  at  the  end  of  the  argument  list.  Always  attempt  to  return  a  meaningful 
value  from  a  function  if  one  is  appropriate.  Here  is  a  slightly  longer  example: 

function  connect (&$dsn,  $persistent  =  false) 

{ 

if  ( is_array ( $dsn) )  { 

$dsninfo  =  &$dsn; 

}  else  { 

$dsninfo  =  DB : :parseDSN ($dsn) ; 

} 

if  ( ! $dsninfo  ||  ! $dsninfo [ ' phptype' ] )  { 
return  $this->raiseError  ( ) ; 

} 

return  true; 

} 


Comments 


Inline  documentation  for  classes  should  follow  the  PHPDoc  convention,  similar  to  Javadoc.  More 
information  about  PHPDoc  can  be  found  here:  http://www.phpdoc.de/ 

Non-documentation  comments  are  strongly  encouraged.  A  general  rule  of  thumb  is  that  if  you  look  at  a 
section  of  code  and  think  "Wow,  I  don’t  want  to  try  and  describe  that",  you  need  to  comment  it  before 
you  forget  how  it  works. 

C  style  comments  (/*  */)  and  standard  C++  comments  (//)  are  both  fine.  Use  of  Perl/shell  style  comments 
(#)  is  discouraged. 


Including  Code 

Anywhere  you  are  unconditionally  including  a  class  file,  use  require_onceO-  Anywhere  you  are 
conditionally  including  a  class  file  (for  example,  factory  methods),  use  include_once  ').  Either  of  these 
will  ensure  that  class  files  are  included  only  once.  They  share  the  same  file  list,  so  you  don’t  need  to 
worry  about  mixing  them  -  a  file  included  with  require_once'j  will  not  be  included  again  by 
include_once')- 


Nota:  include_once;)  and  require_once[)  are  statements,  not  functions.  You  don’t  need  parentheses 
around  the  filename  to  be  included. 
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PHP  Code  Tags 

Always  use  <?php  ?>  to  delimit  PHP  code,  not  the  <?  ?>  shorthand.  This  is  required  for  PEAR 
compliance  and  is  also  the  most  portable  way  to  include  PHP  code  on  differing  operating  systems  and 
setups. 


Header  Comment  Blocks 


All  source  code  files  in  the  core  PEAR  distribution  should  contain  the  following  comment  block  as  the 
header: 

/*  vim:  set  expandtab  tabstop=4  shiftwidth=4 :  */ 

//  + - + 

//  |  PHP  version  4.0  I 

//  + - + 

//  |  Copyright  (c)  1997,  1998,  1999,  2000,  2001  The  PHP  Group  I 

//  + - + 

//  |  This  source  file  is  subject  to  version  2.0  of  the  PHP  license,  I 

//  |  that  is  bundled  with  this  package  in  the  file  LICENSE,  and  is  I 

/ /  |  available  at  through  the  world-wide-web  at  I 

//  |  http://www.php.net/license/2_02.txt.  I 

//  I  If  you  did  not  receive  a  copy  of  the  PHP  license  and  are  unable  to  I 

/ /  |  obtain  it  through  the  world-wide-web,  please  send  a  note  to  I 

//  |  license@php.net  so  we  can  mail  you  a  copy  immediately.  I 


//  + - + 

//  |  Authors:  Original  Author  <author@example . com>  | 

//  |  Your  Name  <you@example . com>  I 

//  + - + 

// 


//  $Id$ 


There’s  no  hard  rule  to  determine  when  a  new  code  contributer  should  be  added  to  the  list  of  authors  for 
a  given  source  file.  In  general,  their  changes  should  fall  into  the  "substantial"  category  (meaning 
somewhere  around  10%  to  20%  of  code  changes).  Exceptions  could  be  made  for  rewriting  functions  or 
contributing  new  logic. 

Simple  code  reorganization  or  bug  fixes  would  not  justify  the  addition  of  a  new  individual  to  the  list  of 
authors. 

Files  not  in  the  core  PEAR  repository  should  have  a  similar  block  stating  the  copyright,  the  license,  and 
the  authors.  All  files  should  include  the  modeline  comments  to  encourage  consistency. 


Using  CVS 


This  section  applies  only  to  packages  using  CVS  at  cvs.php.net. 

Include  the  $Id$  CVS  keyword  in  each  file.  As  each  file  is  edited,  add  this  tag  if  it’s  not  yet  present  (or 
replace  existing  forms  such  as  "Last  Modified:",  etc.). 
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The  rest  of  this  section  assumes  that  you  have  basic  knowledge  about  CVS  tags  and  branches. 

CVS  tags  are  used  to  label  which  revisions  of  the  files  in  your  package  belong  to  a  given  release.  Below 
is  a  list  of  the  required  and  suggested  CVS  tags: 

R  ELEA  S  E_n_  n 

(required)  Used  for  tagging  a  release.  If  you  don’t  use  it,  there’s  no  way  to  go  back  and  retrieve 
your  package  from  the  CVS  server  in  the  state  it  was  in  at  the  time  of  the  release. 


QA  _n_n 

(branch,  optional)  If  you  feel  you  need  to  roll  out  a  release  candidate  before  releasing,  it’s  a  good 
idea  to  make  a  branch  for  it  so  you  can  isolate  the  release  and  apply  only  those  critical  fixes  before 
the  actual  release.  Meanwhile,  normal  development  may  continue  on  the  main  trunk. 

MAINT_n_r! 

(branch,  optional)  If  you  need  to  make  "micro-releases"  (for  example  1.2.1  and  so  on  after  1.2),  you 
can  use  a  branch  for  that  too,  if  your  main  trunk  is  very  active  and  you  want  only  minor  changes 
between  your  micro-releases. 

Only  the  RELEASE  tag  is  required,  the  rest  are  recommended  for  your  convenience. 

Below  is  an  example  of  how  to  tag  the  1.2  release  of  the  "Money _Fast"  package: 

$  cd  pear/Money_Fast 
$  cvs  tag  RELEASE_1_2 

T  Fast.php 
T  README 
T  package. xml 


By  doing  this  you  make  it  possible  for  the  PEAR  web  site  to  take  you  through  the  rest  of  your  release 
process. 

Here’s  an  example  of  how  to  create  a  QA  branch: 

$  cvs  tag  QA_2_0_BP 

$  cvs  rtag  -b  -r  QA_2_0_BP  QA_2_0 
$  cvs  update  -r  QA_2_0 
$  cvs  tag  RELEASE_2_0RC1 

...and  then  the  actual  release,  from  the  same  branch: 

$  cvs  tag  RELEASE_2_0 

The  "QA_2_0_BP"  tag  is  a  "branch  point"  tag,  which  is  the  start  point  of  the  tag.  It’s  always  a  good  idea 
to  start  a  CVS  branch  from  such  branch  points.  MAINT  branches  may  use  the  RELEASE  tag  as  their 
branch  point. 
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Example  URLs 

Use  "example.com"  for  all  example  URLs,  per  RFC  2606. 


Naming  Conventions 

Functions  and  Methods 

Functions  and  methods  should  be  named  using  the  "studly  caps"  style  (also  referred  to  as  "bumpy  case" 
or  "camel  caps").  Functions  should  in  addition  have  the  package  name  as  a  prefix,  to  avoid  name 
collisions  between  packages.  The  initial  letter  of  the  name  (after  the  prefix)  is  lowercase,  and  each  letter 
that  starts  a  new  "word"  is  capitalized.  Some  examples: 


connect() 


getDataf) 


buildS  ome  Widgetf) 


XML RPC serial 


Private  class  members  (meaning  class  members  that  are  intented  to  be  used  only  from  within  the  same 
class  in  which  they  are  declared;  PHP  does  not  yet  support  truly-enforceable  private  namespaces)  are 
preceeded  by  a  single  underscore.  For  example: 


sort() 


initTree() 


$this->_status 


Constants 

Constants  should  always  be  all-uppercase,  with  underscores  to  seperate  words.  Prefix  constant  names 
with  the  uppercased  name  of  the  class/package  they  are  used  in.  For  example,  the  constants  used  by  the 
db  :  :  package  all  begin  with  "db_". 


Global  Variables 

If  your  package  needs  to  define  global  variables,  their  name  should  start  with  a  single  underscore 
followed  by  the  package  name  and  another  underscore.  For  example,  the  PEAR  package  uses  a  global 
variable  called  $_PEAR_destructor_object_list. 
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This  chapter  contains  reference  documentation  for  PEAR  components  that  are  distributed  with  PHP.  It  is 
assumed  that  you  are  already  familiar  with  objects  and  classes 
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PEAR 


(unknown) 


PEAR  base  class 


Synopsis 

require_once  "PEAR.php"; 

class  classname  extends  pear  {  ...  } 


The  PEAR  base  class  provides  standard  functionality  that  is  used  by  most  PEAR  classes.  Normally  you 
never  make  an  instance  of  the  PEAR  class  directly,  you  use  it  by  subclassing  it. 

Its  key  features  are: 

•  request-shutdown  object  "destructors" 

•  error  handling 


If  you  inherit  pear  in  a  class  called  ClassName,  you  can  define  a  method  in  it  called  called 
_ClassName  (the  class  name  with  an  underscore  prepended)  that  will  be  invoked  when  the  request  is 
over.  This  is  not  a  destructor  in  the  sense  that  you  can  "delete"  an  object  and  have  the  destructor  called, 
but  in  the  sense  that  PHP  gives  you  a  callback  in  the  object  when  PHP  is  done  executing.  See  the 
example  below. 


Important! 

In  order  for  destructors  to  work  properly,  you  must  Instantiate  your  class  with  the 
"=&  new"  operator  like  this: 

$obj  =&  new  MyClassO; 


If  you  only  use  "=  new",  the  object  registered  in  PEAR’s  shutdown  list  will  be  a 
copy  of  the  object  at  the  time  the  constructor  is  called,  and  it  will  this  copy’s 
"destructor"  that  will  be  called  upon  request  shutdown. 


PEAR’s  base  class  also  provides  a  way  of  passing  around  more  complex  errors  than  a  true/false  value  or 
a  numeric  code.  A  PEAR  error  is  an  object  that  is  either  an  instance  of  the  class  PEAR_Er  ror,  or  some 
class  inheriting  PEAR_Er ror. 

One  of  the  design  criteria  of  PEAR’s  errors  is  that  it  should  not  force  a  particular  type  of  output  on  the 
user,  it  should  be  possible  to  handle  errors  without  any  output  at  all  if  that  is  desirable.  This  makes  it 
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possible  to  handle  errors  gracefully,  also  when  your  output  format  is  different  from  HTML  (for  example 
WML  or  some  other  XML  format). 

The  error  object  can  be  configured  to  do  a  number  of  things  when  it  is  created,  such  as  printing  an  error 
message,  printing  the  message  and  exiting,  raising  an  error  with  PHP’s  trigger_error')  function,  invoke  a 
callback,  or  none  of  the  above.  This  is  typically  specified  in  PEAR_Er  ror’s  constructor,  but  all  of  the 
parameters  are  optional,  and  you  can  set  up  defaults  for  errors  generated  from  each  object  based  on  the 
pear  class.  See  the  PEAR  error  examples  for  how  to  use  it  and  the  PEAR_Error  reference  for  the  full 
details. 


The  example  below  shows  how  to  use  the  PEAR’s  "poor  man’s  kinda  emulated  destructors"  to 
implement  a  simple  class  that  holds  the  contents  of  a  file,  lets  you  append  data  to  the  object  and  flushes 
the  data  back  to  the  file  at  the  end  of  the  request: 

Ejemplo  1.  PEAR:  emulated  destructors 

require_once  "PEAR.php"; 

class  FileContainer  extends  PEAR 
{ 

var  $file  = 
var  $contents  = 
var  $modified  =  0; 

function  FileContainer ($file) 

{ 

$this->PEAR ( ) ;  //  this  calls  the  parent  class  constructor 
$fp  =  fopen($file,  "r"); 
if  ( ! is_resource ($fp) )  { 

return; 

} 

while  (! empty ( $data  =  fread($fp,  2048)))  { 

$this->contents  .=  $data; 

} 

fclose ( $  f p ) ; 

} 

function  append ($str) 

{ 

$this->contents  .=  $str; 

$this->modif ied++; 

} 

//  The  "destructor"  is  named  like  the  constructor 
//  but  with  an  underscore  in  front, 
function  _FileContainer ( ) 

{ 

if  ($this->modified)  { 

$fp  =  fopen ($this->file,  "w "); 
if  ( ! is_resource ($fp) )  { 

return; 

} 
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fwrite($fp,  $this->contents) ; 
fclose  ($fp) ; 


} 

} 

$fileobj  =&  new  FileContainer("testfile"); 

$f ileob j->append ( "this  ends  up  at  the  end  of  the  file\n"); 

//  When  the  request  is  done  and  PHP  shuts  down,  $fileobj's 
//  "destructor"  is  called  and  updates  the  file  on  disk. 


Nota:  PEAR  "destructors"  use  PHP’s  shutdown  callbacks  |register_shutdown_function;)),  and  you 
can’t  output  anything  from  these  when  PHP  is  running  in  a  web  server.  So  anything  printed  in  a 
"destructor"  gets  lost  except  when  PHP  is  used  in  command-line  mode.  Bummer. 

Also,  see  the  warning  about  how  to  instantiate  objects  if  you  want  to  use  the  destructor. 


The  next  examples  illustrate  different  ways  of  using  PEAR’s  error  handling  mechanism. 


Ejemplo  2.  PEAR  error  example  (1) 

function  mysockopen ( $host  =  "localhost",  $port  =  8090) 

{ 

$fp  =  f sockopen  ( $host ,  $port,  $errno,  $errstr) ; 
if  ( ! is_resource ($fp) )  { 

return  new  PEAR_Error ( $errstr ,  $errno) ; 

} 

return  $fp; 

} 

$sock  =  mysockopen () ; 
if  (PEAR: : isError ($sock) )  { 

print  "mysockopen  error:  " . $sock->getMessage ( ) . "<BR>\n" 

} 


This  example  shows  a  wrapper  to  fsockopen  )  that  delivers  the  error  code  and  message  (if  any)  returned 
by  fsockopen  in  a  PEAR  error  object.  Notice  that  PEAR::isError()  is  used  to  detect  whether  a  value  is  a 
PEAR  error. 

PEAR_Error’s  mode  of  operation  in  this  example  is  simply  returning  the  error  object  and  leaving  the  rest 
to  the  user  (programmer).  This  is  the  default  error  mode. 

In  the  next  example  we’re  showing  how  to  use  default  error  modes: 
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Ejemplo  3.  PEAR  error  example  (2) 

class  TCP_Socket  extends  PEAR 
{ 

var  $sock; 

function  TCP_Socket() 

{ 

$this->PEAR ( ) ; 

} 

function  connect ($host,  $port) 

{ 

$sock  =  f sockopen ( $host ,  $port,  $errno,  $errstr) ; 
if  ( ! is_resource ($sock) )  { 

return  $this->raiseError ($errstr,  $errno) ; 


} 

} 

$sock  =  new  TCP_Socket; 

$sock->setErrorHandling (PEAR_ERROR_DIE) ; 
$sock->connect ( " localhost " ,  8090) ; 
print  "still  alive<BR>\n" ; 


Here,  we  set  the  default  error  mode  to  pear_error_die,  and  since  we  don’t  specify  any  error  mode  in 
the  raiseError  call  (that’d  be  the  third  parameter),  raiseError  uses  the  default  error  mode  and  exits  if 
fsockopen  fails. 


The  PEAR  class  uses  some  global  variables  to  register  global  defaults,  and  an  object  list  used  by  the 
"destructors".  All  of  the  global  variables  associated  with  the  PEAR  class  have  a  _pear_  name  prefix. 


$_PEAR_default_error_mode 

If  no  default  error  mode  is  set  in  an  object,  this  mode  will  be  used.  Must  be  one  of 

pear_error_return,  pear_error_print,  pear_error_trigger,  pear_error_die  or 

PEAR_ERROR_CALLBACK. 

Don’t  set  this  variable  directly,  call  PEAR::setErrorHandling()  as  a  static  method  like  this: 

PEAR: : setErrorHandling (PEAR_ERROR_DIE) ; 


$_PEAR_default_error_options 

If  the  error  mode  is  pear_error_trigger,  this  is  the  error  level  (one  of  e_user_notice, 
E_U S E R_WARN I NG  Or  E_USER_ERROR). 

Don’t  set  this  variable  directly,  call  PEAR::setErrorHandling()  as  a  static  method  like  this: 
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PEAR:  : setErrorHandling (PEAR_ERROR_TRIGGER,  E_U  S  E R_E RRO R )  ; 


$_PEAR_default_error_callback 

If  no  options  parameter  is  used  when  an  error  is  raised  and  the  error  mode  is 
pear_error_CALLBACK,  the  value  of  this  variable  is  used  as  the  callback.  This  means  that  you  can 
switch  the  error  mode  temporarily  and  return  to  callback  mode  without  specifying  the  callback 
function  again.  A  string  value  represents  a  function,  a  two-element  array  with  an  object  at  index  0 
and  a  string  at  index  1  represents  a  method. 

Again,  don’t  set  this  variable  directly,  call  PEAR::setErrorHandling()  as  a  static  method  like  this: 

PEAR: : setErrorHandling (PEAR_ERROR_CALLBACK,  "my_error_handler " ) ; 


Here  is  an  example  of  how  you  can  switch  back  and  forth  without  specifying  the  callback  function 
again: 

PEAR: : setErrorMode (PEAR_ERROR_CALLBACK,  "my_f unct ion_handler " ) ; 
do_some_stuf f ()  ; 

PEAR:  : setErrorMode ( P  E AR_E  RROR_D I E )  ; 
do_some_critical_stuf f () ; 

PEAR: : setErrorMode ( PEAR_ERROR_CALLBACK ) ; 

//  now  we're  back  to  using  my_function_handler  again 


PEAR::PEAR 


PEAR  ()  ( ) 


This  is  the  PEAR  class  constructor.  Call  it  from  the  constructor  of  every  class  inheriting  the  PEAR  class. 

Ejemplo  4.  PEAR  Class  Constructor  Example 

class  MyClass  extends  PEAR 
{ 

var  $foo,  $bar; 

function  MyClass ($foo,  $bar) 

{ 

$this— >PEAR ( ) ; 

$this->foo  =  $foo; 
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} 


$this->bar  =  $bar; 


PEAR::_PEAR 

_PEAR  ()  () 

This  is  the  PEAR  class  destructor.  It  is  called  during  request  shutdown. 

PEAR _ ErrOr  (unknown) 

PEAR  error  mechanism  base  class 

Synopsis 

$err  =  new  PEAR_Error  ( $msg)  ; 

An  error  object  has  a  mode  of  operation  that  can  be  set  with  one  of  the  following  constants: 
PEAR_ERROR_RETURN 

Just  return  the  object,  don’t  do  anything  special  in  PEAR_Error’s  constructor. 
PEAR_ERROR_PRINT 

Print  the  error  message  in  the  constructor.  The  execution  is  not  interrupted. 
PEAR_ERROR_TRIGGER 

Use  PHP’s  trigger_error()  function  to  raise  an  internal  error  in  PHP  The  execution  is  aborted  if  you 
have  defined  your  own  PHP  error  handler  or  if  you  set  the  error  severity  to  E_USER_ERROR. 

PEAR_ERROR_DIE 

Print  the  error  message  and  exit.  Execution  is  of  course  aborted. 

PEAR_ERROR_CALLBACK 

Use  a  callback  function  or  method  to  handle  errors.  Execution  is  aborted. 
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PEAR_Error: :PEAR_Error  ( [message  code  mode  options  user inf o ] ] ] ] ] ) 


Description 

PEAR_Error  constructor.  Parameters: 


message 


error  message,  defaults  to  "unknown  error" 


code 


error  code  (optional) 


mode 


Mode  of  operation.  See  the  error  modes  section  for  details. 


options 

If  the  mode  of  can  have  any  options  specified,  use  this  parameter.  Currently  the  "trigger"  and 
"callback"  modes  are  the  only  using  the  options  parameter.  For  trigger  mode,  this  parameter  is  one 
of  e_user_notice,  E_u S E r_warn I N G  or  e_user_error.  For  callback  mode,  this  parameter- 
should  contain  either  the  callback  function  name  (string),  or  a  two-element  (object,  string)  array 
representing  an  object  and  a  method  name. 
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This  section  holds  the  most  general  questions  about  PHP:  what  it  is  and  what  it  does. 

1.  What  is  PHP? 

From  the  preface  of  the  manual 

PHP  is  an  HTML-embedded  scripting  language.  Much  of  its  syntax  is  borrowed  from  C,  Java  and  Perl 
with  a  couple  of  unique  PHP-specific  features  thrown  in.  The  goal  of  the  language  is  to  allow  web 
developers  to  write  dynamically  generated  pages  quickly. 

A  nice  introduction  to  PHP  by  Stig  Ssether  Bakken  can  be  found  here 
(http://www.zend.com/zend/art/intro.php)  on  the  Zend  website. 


2.  What  is  the  relation  between  the  versions? 

PHP/FI  2.0  is  an  early  and  no  longer  supported  version  of  PHP.  PHP  3  is  the  successor  to  PHP/FI  2.0  and 
is  a  lot  nicer.  PHP  4  is  the  latest  generation  of  PHP,  which  uses  the  Zend  engine  (http://www.zend.com/) 
under  the  hood. 

3.  Can  I  run  several  versions  of  PHP  at  the  same  time? 

Yes.  See  the  install  file  that  is  included  in  the  PHP  4  source  distribution. 

4.  What  are  the  differences  between  PHP  3  and  PHP  4? 

There  are  a  couple  of  articles  (http://www.zend.com/zend/art/)  written  on  this  by  the  authors  of  PHP4. 
Here’s  a  list  of  some  of  the  more  important  new  features: 

•  Extended  API  module. 

•  Generalized  build  process  under  UNIX 

•  Generic  web  server  interface  that  also  supports  multi-threaded  web  servers 

•  Improved  syntax  highlighter 

•  Native  HTTP  session  support 

•  Output  buffering  support 

•  More  powerful  configuration  system 

•  Reference  counting 

Please  see  the  What’s  new  in  PHP4  overview  (http://www.zend.com/zend/whats-new.php)  for  a  detailed 
explanation  of  these  features  and  more. 

5.  I  think  I  found  a  bug!  Who  should  I  tell? 

You  should  go  to  the  PHP  Bug  Database  and  make  sure  the  bug  isn’t  a  known  bug.  If  you  don’t  see  it  in 
the  database,  use  the  reporting  form  to  report  the  bug.  It  is  important  to  use  the  bug  database  instead  of 
just  sending  an  email  to  one  of  the  mailing  lists  because  the  bug  will  have  a  tracking  number  assigned 
and  it  will  then  be  possible  for  you  to  go  back  later  and  check  on  the  status  of  the  bug.  The  bug  database 
can  be  found  at  http://bugs.php.net/. 
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This  section  holds  questions  abuot  how  to  get  in  touch  with  the  PHP  community.  The  best  way  is  the 
mailing  lists. 

1.  Are  there  any  PHP  mailing  lists? 

Of  course!  There  are  many  mailing  lists  for  several  subjects.  A  whole  list  of  mailing  lists  can  be  found  on 
our  Support  (http://www.php.net/support.php)  page. 

The  most  general  mailing  list  is  php-general.  To  subscribe,  send  mail  to 

php-general-subscribe@lists.php.net  (mailto:php-general-subscribe@lists.php.net).  You  don’t  need  to 
include  anything  special  in  the  subject  or  body  of  the  message.  To  unsubscribe,  send  mail  to 
php-general-unsubscribe@lists.php.net  (mailto:php-general-unsubscribe@lists.php.net) 

php-general-unsubscribe@ lists . php . net. 

You  can  also  subscribe  and  unsubscribe  usging  the  web  interface  on  our  Support 
(http://www.php.net/support.php)  page. 


2.  Are  there  any  other  communities? 

There  are  countless  of  them  around  the  world.  We  have  links  for  example  to  some  IRC  servers  and 
foreign  language  mailing  lists  on  our  Support  (http://www.php.net/support.php)  page. 

3.  Help!  I  can’t  seem  to  subscribe/unsubscribe  to/from  one  of  the  mailing  lists! 

If  you  have  problems  subscribing  to  or  unsubscribing  from  the  php-general  mailing  list,  it  may  be 
because  the  mailing  list  software  can’t  figure  out  the  correct  mailing  address  to  use.  If  your  email  address 
was  joeblow@example  .  com,  you  can  send  your  subscription  request  to 

php-general -sub  scribe-  joeblow=example  .  com@  lists  .  php .  net,  or  your  unsubscription 
request  to  php-general-unsubscribe-  joeblow=example  .  com@ lists  .  php  .  net.  Use  similar 
addresses  for  the  other  mailing  lists. 

4.  Is  there  an  archive  of  the  mailing  lists  anywhere? 

Yes,  you  will  find  a  list  of  archive  sites  on  the  Support  (http://www.php.net/support.php)  page.  The 
mailing  list  articles  are  also  archived  as  news  messages.  You  can  access  the  news  server  at 
news://news.php.net/  with  a  news  client.  There  is  also  an  experimental  web  interface  for  the  news  server 
at  http://news.php.net/ 

5.  What  can  I  ask  the  mailing  list? 

Since  PHP  is  growing  more  and  more  popular  by  the  day  the  traffic  has  increased  on  the  php-general 
mailing  list  and  as  of  now  the  list  gets  about  150  to  200  posts  a  day.  Because  of  this  it  is  in  everyones 
interest  that  you  use  the  list  as  a  last  resort  when  you  have  looked  everywhere  else. 

Before  you  post  to  the  list  please  have  a  look  in  this  FAQ  and  the  manual  to  see  if  you  can  find  the  help 
there.  If  there  is  nothing  to  be  found  there  try  out  the  mailing  list  archives  (see  above).  If  you’re  having 
problem  with  installing  or  configuring  PHP  please  read  through  all  included  documentation  and 
README’s.  If  you  still  can’t  find  any  information  that  helps  you  out  you’re  more  than  welcome  to  use 
the  mailing  list. 
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6.  What  information  should  I  include  when  posting  to  the  mailing  list? 

Posts  like  "I  can’t  get  PHP  up  and  running!  Help  me!  What  is  wrong?"  are  of  absolutely  no  use  to 
anyone.  If  you’re  having  problems  getting  PHP  up  and  running  you  must  include  what  operating  system 
you  are  running  on,  what  version  of  PHP  you’re  trying  to  set  up,  how  you  got  it  (pre-compiled,  CVS, 
RPMs  and  so  on),  what  you  have  done  so  far,  where  you  got  stuck  and  the  exact  error  message. 

This  goes  for  any  other  problem  as  well.  You  have  to  include  information  on  what  you  have  done,  where 
you  got  stuck,  what  you’re  trying  to  do  and,  if  applicable,  exact  error  messages.  If  you’re  having 
problems  with  your  source  code  you  need  to  include  the  part  of  the  code  that  isn’t  working.  Do  not 
include  more  code  than  necessary  though!  It  makes  the  post  hard  to  read  and  a  lot  of  people  might  just 
skip  it  all  together  because  of  this.  If  you’re  unsure  about  how  much  information  to  include  in  the  mail 
it’s  better  that  you  include  to  much  than  to  little. 

Another  important  thing  to  remember  is  to  summarize  your  problem  on  the  subject  line.  A  subject  like 
"HELP  MEEEE!!!"  or  "What  is  the  problem  here?"  will  be  ignored  by  the  majority  of  the  readers. 
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This  section  has  details  about  PHP  download  locations,  and  OS  issues. 

1.  Where  can  I  obtain  PHP? 

You  can  download  PHP  from  any  of  the  members  of  the  PHP  network  of  sites.  These  can  be  found  at 
http://www.php.net/.  You  can  also  use  anonymous  CVS  to  get  the  absolute  latest  version  of  the  source. 
For  more  information,  go  to  http://cvs.php.net/. 

2.  Are  pre-compiled  binary  versions  available? 

We  only  distribute  precompiled  binaries  for  Windows  systems,  as  we  are  not  able  to  compile  PHP  for 
every  major  Linux/Unix  platform  with  every  extension  combination.  Also  note,  that  many  Linux 
distributions  come  with  PHP  built  in  these  days.  Windows  binaries  can  be  downloaded  from  our 
Downloads  (http://www.php.net/downloads.php)  page,  for  Linux  binaries,  please  visit  your  distributions 
website. 

3.  Where  can  I  get  libraries  needed  to  compile  some  of  the  optional  PHP  extensions? 

Nota:  Those  marked  with  *  are  not  thread-safe  libraries,  and  should  not  be  used  with  PHP  as  a 
server  module  in  the  multi-threaded  Windows  web  servers  (IIS,  Netscape).  This  does  not  matter  in 
Unix  environments,  yet. 


•  LDAP  (unix)  (ftp://ftp.openldap.org/pub/openldap/openldap-stable.tgz). 

•  LDAP*  (unix)  (ftp://terminator.rs.itd.umich.edU/ldap/ldap-3.3.tar.Z). 

•  LDAP  (unix/win)  (http://developer.netscape.com/tech/directory/downloads.html) :  Netscape 
Directory  (LDAP)  SDK  1.1. 

•  free  LDAP  server  (http://developer.netscape.com/tech/directory/downloads.html). 

•  Berkeley  DB2  (Unix/Win)  (http://www.sleepycat.com/)  :  http://www.sleepycat.com/. 

•  SNMP*  (Unix):  (http://www.ece.ucdavis.edu/ucd-snmp/). 

•  GD*  (Unix/Win)  (http://www.boutell.eom/gd/#buildgd). 

•  mSQL*  (Win)  (http://blnet.com/msqlpc/). 

•  mSQL*  (Unix)  (http://www.hughes.com.au/). 

•  MySQL*  (Unix)  (http://www.mysql.com/). 

•  IMAP*  (Win/Unix)  (ftp://ftp.cac.washington.edU/imap/old/imap-4.5.tar.Z). 

•  Sybase-CT*  (Linux,  libc5)  (http://www.php.net/extra/ctlib-linux-elf.tar.gz)  :  Available  locally. 

•  FreeType  (libttf):  (http://www.freetype.org/). 

•  ZLib  (Unix/Win32)  (http://www.cdrom.com/pub/infozip/zlib/). 

•  expat  XML  parser  (Unix/Win32)  (http://www.jclark.com/xml/expat.html). 

•  PDFLib  (http://www.pdflib.com/). 

•  mcrypt  (ftp://argeas.cs-net.gr/pub/unix/mcrypt/). 

•  mhash  (http://sasweb.de/mhash/). 
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•  tllib  (http://www.neuroinformatik.mhr-uni-bochum.de/ini/PEOPLE/rmz/tllib/tllib.html). 

•  dmalloc  (http://www.dmalloc.com/). 

•  aspell  (http://download.sourceforge.net/aspell/aspell-.29. 1  .tar.gz). 

•  readline  (ftp://prep.ai.mit.edu/pub/gnu/readline/). 


4.  How  do  I  get  these  libraries  to  work? 

You  will  need  to  follow  instructions  provided  with  the  library.  Some  of  these  libraries  are  detected 
automatically  when  you  run  the  ’configure’  script  of  PHP  (such  as  the  GD  library),  and  others  you  will 
have  to  enable  using  ’ — with-EXTENSlON’  options  to  ’configure’.  Run  ’configure  — help’  for  a 
listing  of  these. 

5.  I  got  the  latest  version  of  the  PHP  source  code  from  the  CVS  repository  on  my  Windows  machine, 
what  do  I  need  to  compile  it? 

First,  you  will  need  Microsoft  Visual  C++  v6  (v5  may  do  it  also,  but  we  do  it  with  v6),  and  you  will  need 
some  support  files.  See  the  manual  section  about  building  PHP  from  source  on  Windows. 

6.  Where  do  I  find  the  Browser  Capabilities  File? 

You  can  find  a  browscap .  ini  file  at  http://www.cyscape.com/asp/browscap/. 
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This  section  holds  common  questions  about  relation  between  PHP  and  databases.  Yes,  PHP  can  access 
virtually  any  database  available  today. 

1.  I  heard  it’s  possible  to  access  Microsoft  SQL  Server  from  PHP.  How? 

On  Windows  machines,  you  can  simply  use  the  included  ODBC  support  and  the  correct  ODBC  driver. 

On  Unix  machines,  you  can  use  the  Sybase-CT  driver  to  access  Microsoft  SQL  Servers  because  they  are 
(at  least  mostly)  protocol-compatible.  Sybase  has  made  a  free  version  of  the  necessary  libraries  for  Linux 
systems  (http://www.php.net/extra/ctlib-linux-elf.tar.gz).  For  other  Unix  operating  systems,  you  need  to 
contact  Sybase  for  the  correct  libraries.  Also  see  the  answer  to  the  next  question. 


2.  Can  I  access  Microsoft  Access  databases? 

Yes.  You  already  have  all  the  tools  you  need  if  you  are  running  entirely  under  Windows  9x/Me,  or 
NT/2000,  where  you  can  use  ODBC  and  Microsoft’s  ODBC  drivers  for  Microsoft  Access  databases. 

If  you  are  running  PHP  on  a  Unix  box  and  want  to  talk  to  MS  Access  on  a  Windows  box  you  will  need 
Unix  ODBC  drivers.  OpenLink  Software  (http://www.openlinksw.com/)  has  Unix-based  ODBC  drivers 
that  can  do  this.  There  is  a  free  pilot  program  where  you  can  download  an  evaluation  copy  that  doesn’t 
expire  and  prices  start  at  $675  for  the  commercial  supported  version. 

Another  alternative  is  to  use  an  SQL  server  that  has  Windows  ODBC  drivers  and  use  that  to  store  the 
data,  which  you  can  then  access  from  Microsoft  Access  (using  ODBC)  and  PHP  (using  the  built  in 
drivers),  or  to  use  an  intermediary  file  format  that  Access  and  PHP  both  understand,  such  as  flat  files  or 
dBase  databases.  On  this  point  Tim  Hayes  from  OpenLink  software  writes: 

Using  another  database  as  an  intermediary  is  not  a  good  idea,  when  you  can 
use  ODBC  from  PHP  straight  to  your  database  -  i.e.  with  OpenLink' s  drivers.  If 
you  do  need  to  use  an  intermediary  file  format,  OpenLink  have  now  released 
Virtuoso  (a  virtual  database  engine)  for  NT,  Linux  and  other  unix  platforms. 
Please  visit  our  website  (http://www.openlinksw.com/)  for  a  free  download. 


One  option  that  has  proven  successful  is  to  use  MySQL  and  its  MyODBC  drivers  on  Windows  and 
synchronizing  the  databases.  Steve  Lawrence  writes: 


•  Install  MySQL  on  your  platform  according  to  instructions  with  MySQL.  Latest  available  from 
www.mysql.com (http://www.mysql.com/)  (get  it  from  your  mirror!).  No  special  configuration 
required  except  when  you  set  up  a  database,  and  configure  the  user  account,  you  should  put  %  in  the 
host  field,  or  the  host  name  of  the  Windows  computer  you  wish  to  access  MySQL  with.  Make  a  note 
of  your  server  name,  username,  and  password. 

•  Download  the  MyODBC  for  Windows  driver  from  the  MySQL  site.  Latest  release  is 
myodbc-2_50_19-win95.zip  (NT  available  too,  as  well  as  source  code).  Install  it  on  your  Windows 
machine.  You  can  test  the  operation  with  the  utilities  included  with  this  program. 

•  Create  a  user  or  system  dsn  in  your  ODBC  administrator,  located  in  the  control  panel.  Make  up  a  dsn 
name,  enter  your  hostname,  user  name,  password,  port,  etc  for  you  MySQL  database  configured  in 
step  1. 
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•  Install  Access  with  a  full  install,  this  makes  sure  you  get  the  proper  add-ins.,  at  the  least  you  will  need 
ODBC  support  and  the  linked  table  manager. 

•  Now  the  fun  part!  Create  a  new  access  database.  In  the  table  window  right  click  and  select  Link 
Tables,  or  under  the  file  menu  option,  select  Get  External  Data  and  then  Link  Tables.  When  the  file 
browser  box  comes  up,  select  files  of  type:  ODBC.  Select  System  dsn  and  the  name  of  your  dsn 
created  in  step  3.  Select  the  table  to  link,  press  ok,  and  presto!  You  can  now  open  the  table  and 
add/delete/edit  data  on  your  MySQL  server!  You  can  also  build  queries,  import/export  tables  to 
MySQL,  build  forms  and  reports,  etc. 


Tips  and  Tricks: 

•  You  can  construct  your  tables  in  access  and  export  them  to  MySQL,  then  link  them  back  in.  That 
makes  table  creation  quick. 

•  When  creating  tables  in  access,  you  must  have  a  primary  key  defined  in  order  to  have  write  access  to 
the  table  in  access.  Make  sure  you  create  a  primary  key  in  MySQL  before  linking  in  access 

•  If  you  change  a  table  in  MySQL,  you  have  to  re-link  it  in  Access.  Go  to  tools>add-ins>linked  table 
manager,  cruise  to  your  ODBC  DSN,  and  select  the  table  to  re-link  from  there,  you  can  also  move  your 
dsn  source  around  there,  just  hit  the  always  prompt  for  new  location  checkbox  before  pressing  ok. 


3.  I  upgraded  to  PHP  4,  and  now  mysql  keeps  telling  me  "Warning:  MySQL:  Unable  to  save  result  set  in 
...".What’s  up? 

Most  likely  what  has  happened  is,  PHP  4  was  compiled  with  the  with-mysqF  option,  without 
specifying  the  path  to  MySQL.  This  means  PHP  is  using  its  built-in  MySQL  client  library.  If  your  system 
is  running  applications,  such  as  PHP  3  as  a  concurrent  Apache  module,  or  auth-mysql,  that  use  other 
versions  of  MySQL  clients,  then  there  is  a  conflict  between  the  two  differing  versions  of  those  clients. 

Recompiling  PHP  4,  and  adding  the  path  to  MySQL  to  the  flag,  with-mysql=/your/path/to/mysqT 
usually  solves  the  problem. 


4.  After  installing  shared  MySQL  support,  Apache  dumps  core  as  soon  as  libphp4.so  is  loaded.  Can  this 
be  fixed? 

If  your  MySQL  libs  are  linked  against  pthreads  this  will  happen.  Check  using  ldd.  If  they  are,  grab  the 
MySQL  tarball  and  compile  from  source,  or  recompile  from  the  source  rpm  and  remove  the  switch  in  the 
spec  file  that  turns  on  the  threaded  client  code.  Either  of  these  suggestions  will  fix  this.  Then  recompile 
PHP  with  the  new  MySQL  libs. 

5.  Why  do  I  get  an  error  that  looks  something  like  this:  "Warning:  0  is  not  a  MySQL  result  index  in 
<file>  on  line  <x>"  or  "Warning:  Supplied  argument  is  not  a  valid  MySQL  result  resource  in  <file>  on 
line  <x>? 

You  are  trying  to  use  a  result  identifier  that  is  0.  The  0  indicates  that  your  query  failed  for  some  reason. 
You  need  to  check  for  errors  after  submitting  a  query  and  before  you  attempt  to  use  the  returned  result 
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identifier.  The  proper  way  to  do  this  is  with  code  similar  to  the  following: 

$result  =  mysql_query ( "SELECT  *  FROM  tables_priv" ) ; 
if  ( ! $result)  { 

echo  mysql_error ( ) ; 
exit ; 


or 

$result  =  mysql_query ( "SELECT  *  FROM  tables_priv" ) 
or  die ("Bad  query:  " . mysql_error ( ) ) ; 
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This  section  holds  common  questions  about  the  way  to  install  PHP.  PHP  is  available  for  almost  any  OS 
(except  maybe  for  MacOS  before  OSX),  and  almost  any  web  server. 

To  install  PHP,  follow  the  instructions  in  the  INSTALL  (http://cvs.php.net/co.php/php4/INSTALL)  file 
located  in  the  distribution.  Windows  users  should  also  read  the  install.txt 

(http://cvs.php.net/co.php/php4/win32/install.txt)  file.  There  are  also  some  helpful  hints  for  Windows 
users  here. 

1.  Unix/Windows:  Where  should  my  php.ini  file  be  located? 

By  default  on  UNIX  it  should  be  in  /usr/local/lib.  Most  people  will  want  to  change  this  at 
compile-time  with  the  — with-config-file-path  flag.  You  would,  for  example,  set  it  with  something  like: 

— wit h- con fig- file-pat h=/etc 


And  then  you  would  copy  php .  ini-dist  from  the  distribution  to  /etc/php .  ini  and  edit  it  to  make 
any  local  changes  you  want. 

On  Windows  the  default  path  for  the  php  .ini  file  is  the  Windows  directory. 


2.  Unix:  I  installed  PHP,  but  every  time  I  load  a  document,  I  get  the  message  ’Document  Contains  No 
Data’ !  What’s  going  on  here? 

This  probably  means  that  PHP  is  having  some  sort  of  problem  and  is  core-dumping.  Look  in  your  server 
error  log  to  see  if  this  is  the  case,  and  then  try  to  reproduce  the  problem  with  a  small  test  case.  If  you 
know  how  to  use  ’gdb’,  it  is  very  helpful  when  you  can  provide  a  backtrace  with  your  bug  report  to  help 
the  developers  pinpoint  the  problem.  If  you  are  using  PHP  as  an  Apache  module  try  something  like: 

•  Stop  your  httpd  processes 

•  gdb  httpd 

•  Stop  your  httpd  processes 

•  >  run  -X  -f  /path/to/httpd.conf 

•  Then  fetch  the  URL  causing  the  problem  with  your  browser 

•  >  run  -X  -f  /path/to/httpd.conf 

•  If  you  are  getting  a  core  dump,  gdb  should  inform  you  of  this  now 

•  type:  bt 

•  You  should  include  your  backtrace  in  your  bug  report.  This  should  be  submitted  to  http://bugs.php.net/ 

If  your  script  uses  the  regular  expression  functions  ( ereg ')  and  friends),  you  should  make  sure  that  you 
compiled  PHP  and  Apache  with  the  same  regular  expression  package.  This  should  happen  automatically 
with  PHP  and  Apache  1.3.x 
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3.  Unix:  I  installed  PHP  using  RPMS,  but  Apache  isn’t  processing  the  PHP  pages!  What’s  going  on 
here? 

Assuming  you  installed  both  Apache  and  PHP  from  RPM  packages,  you  need  to  uncomment  or  add 
some  or  all  of  the  following  lines  in  your  http .  conf  file: 

#  Extra  Modules 
AddModule  mod_php . c 
AddModule  mod_php3 . c 
AddModule  mod_perl.c 

#  Extra  Modules 


LoadModule 

php_module 

modules /mod  php . so 

LoadModule 

php3_module 

modules/ libphp3 . so 

/* 

for  PHP  3 

*/ 

LoadModule 

LoadModule 

php4_module 

perl_module 

modules/ libphp4 . so 
modules/ libperl . so 

/* 

for  PHP  4 

*/ 

And  add: 

AddType  application/x-httpd-php3  .php3  /*  for  PHP  3  */ 

AddType  application/x-httpd-php  .php  /*  for  PHP  4  */ 


...  to  the  global  properties,  or  to  the  properties  of  the  VirtualDomain  you  want  to  have  PHP  support  added 
to. 

4.  Unix:  I  installed  PHP  3  using  RPMS,  but  it  doesn’t  compile  with  the  database  support  I  need!  What’s 
going  on  here? 

Due  to  the  way  PHP  3  built,  it  is  not  easy  to  build  a  complete  flexible  PHP  RPM.  This  issue  is  addressed 
in  PHP  4.  For  PHP  3,  we  currently  suggest  you  use  the  mechanism  described  in  the  INSTALL.REDHAT 
file  in  the  PHP  distribution.  If  you  insist  on  using  an  RPM  version  of  PHP  3,  read  on... 

The  RPM  packagers  are  setting  up  the  RPMS  to  install  without  database  support  to  simplify  installations 
and  because  RPMS  use  /usr/  instead  of  the  standard  /usr/local/  directory  for  files.  You  need  to  tell  the 
RPM  spec  file  which  databases  to  support  and  the  location  of  the  top-level  of  your  database  server. 

This  example  will  explain  the  process  of  adding  support  for  the  popular  MySQL  database  server,  using 
the  mod  installation  for  Apache. 

Of  course  all  of  this  information  can  be  adjusted  for  any  database  server  that  PHP  supports.  We  will 
assume  you  installed  MySQL  and  Apache  completely  with  RPMS  for  this  example  as  well. 

•  First  remove  mod_php3  : 

rpm  -e  mod_php3 


•  Then  get  the  source  rpm  and  INSTALL  it,  NOT  —rebuild 

rpm  -Uvh  mod_php3-3 . 0 . 5-2 . src . rpm 


•  Then  edit  the  /usr/src/redhat/SPECS/mod_php3  .  spec  file 
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In  the  %build  section  add  the  database  support  you  want,  and  the  path. 
For  MySQL  you  would  add 

— with-mysql=/usr  \ 

The  %build  section  will  look  something  like  this: 

./configure  — prefix=/usr  \ 

— with-apxs=/usr/sbin/apxs  \ 

— with-conf ig-f ile-path=/usr/lib  \ 

--enable-debug=no  \ 

--enable-safe-mode  \ 

— with-exec-dir=/usr/bin  \ 

— with-mysql=/usr  \ 

— with- system-regex 


•  Once  this  modification  is  made  then  build  the  binary  rpm  as  follows: 

rpm  -bb  /usr/src/redhat/SPECS/mod_php3 . spec 

•  Then  install  the  rpm 

rpm  -ivh  /usr/src/redhat/RPMS/i386/mod_php3-3 . 0 . 5-2 . i386 . rpm 

Make  sure  you  restart  Apache,  and  you  now  have  PHP  3  with  MySQL  support  using  RPM’s.  Note  that  it 
is  probably  much  easier  to  just  build  from  the  distribution  tarball  of  PHP  3  and  follow  the  instructions  in 
install  .  redhat  found  in  that  distribution. 


5.  Unix:  I  patched  Apache  with  the  FrontPage  extensions  patch,  and  suddenly  PHP  stopped  working.  Is 
PHP  incompatible  with  the  Apache  FrontPage  extensions? 

No,  PHP  works  fine  with  the  FrontPage  extensions.  The  problem  is  that  the  FrontPage  patch  modifies 
several  Apache  structures,  that  PHP  relies  on.  Recompiling  PHP  (using  ’make  clean  ;  make’)  after  the  FP 
patch  is  applied  would  solve  the  problem. 

6.  Unix/Windows:  I  have  installed  PHP,  but  when  I  try  to  access  a  PHP  script  file  via  my  browser,  I  get  a 
blank  screen. 

Do  a  ’view  source’  in  the  web  browser  and  you  will  probably  find  that  you  can  see  the  source  code  of 
your  PHP  script.  This  means  that  the  web  server  did  not  send  the  script  to  PHP  for  interpretation. 
Something  is  wrong  with  the  server  configuration  -  double  check  the  server  configuration  against  the 
PHP  installation  instructions. 
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7.  Unix/Windows:  I  have  installed  PHP,  but  when  try  to  access  a  PHP  script  file  via  my  browser,  I  get  a 
server  500  error. 

Something  went  wrong  when  the  server  tried  to  run  PHP  To  get  to  see  a  sensible  error  message,  from  the 
command  line,  change  to  the  directory  containing  the  PHP  executable  (php .  exe  on  Windows)  and  run 
php  -i.  If  PHP  has  any  problems  running,  then  a  suitable  error  message  will  be  displayed  which  will 
give  you  a  clue  as  to  what  needs  to  be  done  next.  If  you  get  a  screen  full  of  html  codes  (the  output  of  the 
phpinfo ')  function)  then  PHP  is  working,  and  your  problem  may  be  related  to  your  server  configuration 
which  you  should  double  check. 

8.  Windows:  I  have  installed  PHP,  but  when  I  to  access  a  PHP  script  file  via  my  browser,  I  get  the  error: 

cgi  error: 

The  specified  CGI  application  misbehaved  by  not 
returning  a  complete  set  of  HTTP  headers. 

The  headers  it  did  return  are : 


This  error  message  means  that  PHP  failed  to  output  anything  at  all.  To  get  to  see  a  sensible  error 
message,  from  the  command  line,  change  to  the  directory  containing  the  PHP  executable  (php .  exe  on 
Windows)  and  run  php  -i.  If  PHP  has  any  problems  running,  then  a  suitable  error  message  will  be 
displayed  which  will  give  you  a  clue  as  to  what  needs  to  be  done  next.  If  you  get  a  screen  full  of  html 
codes  (the  output  of  the  phpinfo')  function)  then  PHP  is  working. 

Once  PHP  is  working  at  the  command  line,  try  accessing  the  script  via  the  browser  again.  If  it  still  fails 
then  it  could  be  one  of  the  following: 

•  File  permissions  on  your  PHP  script,  php .  exe,  php4ts  .  dll,  php .  ini  or  any  PHP  extensions  you 
are  trying  to  load  are  such  that  the  anonymous  internet  user  iSUR_<machinename>  cannot  access 
them. 

•  The  script  file  does  not  exist  (or  possibly  isn’t  where  you  think  it  is  relative  to  your  web  root 
directory).  Note  that  for  IIS  you  can  trap  this  error  by  ticking  the  ’check  file  exists’  box  when  setting 
up  the  script  mappings  in  the  Internet  Services  Manager.  If  a  script  file  does  not  exist  then  the  server 
will  return  a  404  error  instead.  There  is  also  the  additional  benefit  that  IIS  will  do  any  authentication 
required  for  you  based  on  the  NTLanMan  permissions  on  your  script  file. 


9.  Windows:  I’ve  followed  all  the  instructions,  but  still  can’t  get  PHP  and  IIS  to  work  together! 

Make  sure  any  user  who  needs  to  run  a  PHP  script  has  the  rights  to  run  php .  exe !  IIS  uses  an  anonymous 
user  which  is  added  at  the  time  IIS  is  installed.  This  user  needs  rights  to  php .  exe.  Also,  any 
authenticated  user  will  also  need  rights  to  execute  php .  exe.  And  for  HS4  you  need  to  tell  it  that  PHP  is 
a  script  engine. 
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This  section  gathers  most  common  errors  that  occur  at  build  time. 

1.  I  got  the  latest  version  of  PHP  using  the  anonymous  CVS  service,  but  there’s  no  configure  script! 

You  have  to  have  the  GNU  autoconf  package  installed  so  you  can  generate  the  configure  script  from 
configure. in.  Just  run  ./buildconf  in  the  top-level  directory  after  getting  the  sources  from  the  CVS  server. 
(Also,  unless  you  run  configure  with  the  — enable-maintainer-mode  option,  the  configure  script 
will  not  automatically  get  rebuilt  when  the  configure. in  file  is  updated,  so  you  should  make  sure  to  do 
that  manually  when  you  notice  configure. in  has  changed.  One  symptom  of  this  is  finding  things  like 
@VARIABLE@  in  your  Makefile  after  configure  or  config. status  is  run.) 

2.  I’m  having  problems  configuring  PHP  to  work  with  Apache.  It  says  it  can’t  find  httpd.h,  but  it’s  right 
where  I  said  it  is! 

You  need  to  tell  the  configure/setup  script  the  location  of  the  top-level  of  your  Apache  source  tree.  This 
means  that  you  want  to  specify  ’ — with-apache=/path/to/apache’  and  not 
’--with-apache=/path/to/ apache/ src’. 

3.  When  I  run  configure,  it  says  that  it  can’t  find  the  include  files  or  library  for  GD,  gdbm,  or  some  other 
package ! 

You  can  make  the  configure  script  looks  for  header  files  and  libraries  in  non-standard  locations  by 
specifying  additional  flags  to  pass  to  the  C  preprocessor  and  linker,  such  as: 

CPPFLAGS=-I /path/to/ include  LDFLAGS=-L/path/to/ library  . / configure 


If  you’re  using  a  csh-variant  for  your  login  shell  (why?),  it  would  be: 

env  CPPFLAGS=-I/path/to/include  LDFLAGS=-L/path/to/library  ./configure 


4.  When  it  is  compiling  the  file  language-parser.tab.c,  it  gives  me  errors  that  say  ’yytname  undeclared’. 

You  need  to  update  your  version  of  Bison.  You  can  find  the  latest  version  at 
ftp://ftp.gnu.org/pub/gnu/bison/. 

5.  When  I  run  ’make’,  it  seems  to  run  fine  but  then  fails  when  it  tries  to  link  the  final  application 
complaining  that  it  can’t  find  some  files. 

Some  old  versions  of  make  that  don’t  correctly  put  the  compiled  versions  of  the  files  in  the  functions 
directory  into  that  same  directory.  Try  running  "cp  *.o  functions"  and  then  re-running  ’make'  to  see  if 
that  helps.  If  it  does,  you  should  really  upgrade  to  a  recent  version  of  GNU  make. 

6.  When  linking  PHP,  it  complains  about  a  number  of  undefined  references. 

Take  a  look  at  the  link  line  and  make  sure  that  all  of  the  appropriate  libraries  are  being  included  at  the 
end.  Common  ones  that  you  might  have  missed  are  ’-ldl’  and  any  libraries  required  for  any  database 
support  you  included. 

If  you’re  linking  with  Apache  1.2.x,  did  you  remember  to  add  the  appropriate  information  to  the 
EXTRA_LIBS  line  of  the  Configuration  file  and  re-rerun  Apache’s  Configure  script?  See  the  INSTALL 
(http://cvs.php.net/co.php/php4/INSTALL)  file  that  comes  with  the  distribution  for  more  information. 
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Some  people  have  also  reported  that  they  had  to  add  ’-ldl’  immediately  following  ’libphp3  .  a’  when 
linking  with  Apache. 


7.  I  can’t  figure  out  how  to  build  PHP  with  Apache  1.3. 

This  is  actually  quite  easy.  Follow  these  steps  carefully: 

•  Grab  the  latest  Apache  1.3  distribution  from  http://www.apache.org/dist/. 

•  Ungzip  and  untar  it  somewhere,  for  example  /usr/local/src/apache-1 . 3. 

•  Compile  PHP  by  first  running  ./configure  —  with-apache=/<path>/apache-1.3  (substitute  <path>  for 
the  actual  path  to  your  apache- 1.3  directory. 

•  Type  ’  make’  followed  by  ’make  install’  to  build  PHP  and  copy  the  necessary  files  to  the  Apache 
distribution  tree. 

•  Change  directories  into  to  your  /<path>/apache-l .  3/src  directory  and  edit  the  Configuration 
file.  At  the  end  of  the  file,  add:  AddModule  modules/php3/ libphp3  .  a. 

•  Type:  ’./Configure’  followed  by  ’make’. 

•  You  should  now  have  a  PHP-enabled  httpd  binary! 

Note:  :  You  can  also  use  the  new  Apache  .  /configure  script.  See  the  instructions  in  the 

readme  .  configure  file  which  is  part  of  your  Apache  distribution.  Also  have  a  look  at  the  install  file 

in  the  PHP  distribution. 


8.  I  have  followed  all  the  steps  to  install  the  Apache  module  version  on  UNIX,  and  my  PHP  scripts  show 
up  in  my  browser  or  I  am  being  asked  to  save  the  file. 

This  means  that  the  PHP  module  is  not  getting  invoked  for  some  reason.  Three  things  to  check  before 
asking  for  further  help: 

•  Make  sure  that  the  httpd  binary  you  are  running  is  the  actual  new  httpd  binary  you  just  built.  To  do 
this,  try  running:  /path/to/binary/httpd  -1 

If  you  don’t  see  mod_php3 .  c  listed  then  you  are  not  running  the  right  binary.  Find  and  install  the 
correct  binary. 


•  Make  sure  you  have  added  the  correct  Mime  Type  to  one  of  your  Apache  .  conf  files.  It  should  be: 

AddType  application/x-httpd-php3  . php3 (for  PHP  3) 

or  AddType  application/x-httpd-php  . php  (for  PHP  4) 

Also  make  sure  that  this  AddType  line  is  not  hidden  away  inside  a  <Virtualhost>  or  <Directory>  block 
which  would  prevent  it  from  applying  to  the  location  of  your  test  script. 


•  Finally,  the  default  location  of  the  Apache  configuration  files  changed  between  Apache  1 .2  and 
Apache  1.3.  You  should  check  to  make  sure  that  the  configuration  file  you  are  adding  the  AddType 
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line  to  is  actually  being  read.  You  can  put  an  obvious  syntax  error  into  your  httpd.conf  file  or  some 
other  obvious  change  that  will  tell  you  if  the  file  is  being  read  correctly. 

9.  It  says  to  use:  — activate-module=src/modules/php4/libphp4  .  a,  but  that  file  doesn’t  exist, 
so  I  changed  it  to  — act i vat e-module=src /module s/php 4/ libmodphp4  .  a  and  it  doesn’t  work!? 
What’s  going  on? 

Well,  you  decided  to  try  to  outsmart  the  people  who  wrote  those  nice  step-by-step  instructions  for  you 
and  you  have  now  discovered  that  these  people  cannot  be  outsmarted.  The  libphp4.a  file  is  not  supposed 
to  exist.  The  Apache  build  process  will  create  it. 

10.  When  I  try  to  build  Apache  with  PHP  as  a  static  module  using 

— activate-module=src/modules/php4/libphp4  .  a  it  tells  me  that  my  compiler  is  not  ANSI 
compliant. 

This  is  a  misleading  error  message  from  Apache  that  has  been  fixed  in  more  recent  versions. 

11.  When  I  try  to  build  PHP  using  — with-apxs  I  get  strange  error  messages. 

There  are  three  things  to  check  here.  First,  for  some  reason  when  Apache  builds  the  apxs  Perl  script,  it 
sometimes  ends  up  getting  built  without  the  proper  compiler  and  flags  variables.  Edit  your  apxs 
(sometimes  found  in  /usr/local/apache/bin/apxs  or  /usr/sbin/apxs)  and  check  for  these  lines: 

my  $CFG_CFLAGS_SHLIB  =  '  ';  #  substituted  via  Makefile . tmpl 

my  $CFG_LD_SHLIB  =  '  ';  #  substituted  via  Makefile . tmpl 

my  $CFG_LDFLAGS_SHLIB  =  '  ';  #  substituted  via  Makefile . tmpl 


If  this  is  what  you  see,  you  have  found  your  problem.  Change  these  lines  to  say: 

my  $CFG_CFLAGS_SHLIB  =  ' -fpic  -DSHARED_MODULE ' ;  #  substituted  via  Makefile . tmpl 

my  $CFG_LD_SHLIB  =  ' gcc' ;  #  substituted  via  Makefile . tmpl 

my  $CFG_LDFLAGS_SHLIB  =  q(-shared);#  substituted  via  Makefile . tmpl 

The  second  possible  problem  should  only  be  an  issue  on  RedHat-6. 1/6.2.  The  apxs  script  RedHat  ships  is 
broken.  Look  for  this  line: 

my  $CFG_LIBEXECDIR  =  'modules';  #  substituted  via  APACI  install 


If  you  see  the  above  line,  change  it  to  this: 

my  $CFG_LIBEXECDIR  =  ' /usr / lib/apache ' ;  #  substituted  via  APACI  install 


Last,  if  you  reconfigure/reinstall  Apache,  add  a  ’make  clean’  to  the  process  after  ’./configure’  and  before 
’make’. 

12.  During  ’make’,  I  get  errors  in  microtime,  and  a  lot  of  ’RUSAGE_’  stuff. 

During  the  ’make’  portion  of  installation,  if  you  encounter  problems  that  look  similar  to  this: 

microtime. c:  In  function  'php_if_getrusage' : 
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microtime . c : 94 :  storage  size  of  'usg'  isn't  known 

microtime . c : 97 :  'RUSAGE_SELF'  undeclared  (first  use  in  this  function) 
microtime . c : 97 :  (Each  undeclared  identifier  is  reported  only  once 
microtime . c : 97 :  for  each  function  it  appears  in.) 

microtime . c : 103 :  'RUSAGE_CHILDREN'  undeclared  (first  use  in  this  function) 
make[3] :  ***  [microtime . lo]  Error  1 

make[3]:  Leaving  directory  '/home/master/php-4 . 0 . 1/ext/standard' 
make [2] :  ***  [all-recursive]  Error  1 

make [2]:  Leaving  directory  '/home/master/php-4 . 0 . 1/ext/standard' 
make[l] :  ***  [all-recursive]  Error  1 

make[l]:  Leaving  directory  '/home/master/php-4 . 0 . 1/ext' 
make:  ***  [all-recursive]  Error  1 


Your  system  is  broken.  You  need  to  fix  your  /usr/include  files  either  by  making  sure  your 
/usr/include/linux  symlink  is  pointing  to  the  right  place  in  your  kernel  sources  or  by  installing  a 
glibc-devel  package  that  matches  your  glibc.  This  has  absolutely  nothing  to  do  with  PHP.  To  prove  this  to 
yourself,  try  this  simple  test: 

$  cat  >test.c  <<X 
linclude  <sys/resource.h> 

X 

$  gcc  -E  test.c  >/dev/null 


If  that  spews  out  errors,  you  know  your  include  files  are  messed  up. 
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This  section  gathers  most  common  errors  you  can  face,  while  writing  PHP  scripts. 

1.  I  would  like  to  write  a  generic  PHP  script  that  can  handle  data  coming  from  any  form.  How  do  I  know 
which  POST  method  variables  are  available? 

Make  sure  that  the  track_vars  feature  is  enabled  in  your  php .  ini  file.  Since  PHP  4.0.3,  this  feature  is 
always  on.  When  track_vars  is  on,  it  creates  some  associative  arrays,  the  most  important  here  is: 

$http _ post_vars.  So,  to  write  a  generic  script  to  handle  POST  method  variables  you  would  need 

something  similar  to  the  following: 


foreach  ( $HTTP_POST_VARS  as  $var  =>  $value)  { 
echo  "$var  =  $value<br>\n"; 

} 


How  can  I  do  this 

You  should  also  have 


3.  When  I  do  the  following,  the  output  is  printed  in  the  wrong  order: 

function  myfunc ( $argument ) 

{ 

echo  $argument  +  10; 

} 

$variable  =  10; 

echo  "myfunc ($variable)  =  "  .  myfunc ($variable); 


2.  I  need  to  convert  all  single-quotes  (’)  to  a  backslash  followed  by  a  single-quote, 
with  a  regular  expression? 

First  off,  take  a  look  at  the  addslashes ')  function.  It  will  do  exactly  what  you  want, 
a  look  at  the  magic_quotes_gpc  directive  in  your  php .  ini  file. 


what’s  going  on? 

To  be  able  to  use  the  results  of  your  function  in  an  expression  (such  as  concatenating  it  with  other  strings 
in  the  example  above),  you  need  to  return  the  value,  not  echo  3  it. 

4.  Hey,  what  happened  to  my  newlines? 


<pre> 

<?php  echo  "This  should  be  the  first  line.";  ?> 

<?php  echo  "This  should  show  up  after  the  new  line  above.";  ?> 
</pre> 


In  PHP,  the  ending  for  a  block  of  code  is  either  "?>"  or  "?>\n"  (where  \n  means  a  newline).  So  in  the 
example  above,  the  echoed  sentences  will  be  on  one  line,  because  PHP  ommits  the  newlines  after  the 
block  ending.  This  means  that  you  need  to  insert  an  extra  newline  after  each  block  of  PHP  code  to  make 
it  print  out  one  newline. 
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Why  does  PHP  do  this?  Because  when  formatting  normal  HTML,  this  usually  makes  your  life  easier 
because  you  don’t  want  that  newline,  but  you’d  have  to  create  extremely  long  lines  or  otherwise  make  the 
raw  page  source  unreadable  to  achieve  that  effect. 


5.  I  need  to  access  information  in  the  request  header  directly.  How  can  I  do  this? 

The  getallheaders ')  function  will  do  this  if  you  are  running  PHP  as  an  Apache  module.  So,  the  following 
bit  of  code  will  show  you  all  the  request  headers: 


$headers  =  getallheaders () ; 
foreach  ($headers  as  $name  =>  $content)  { 
echo  "headers [ $name ]  =  $content<br>\n" ; 

} 


6.  When  I  try  to  use  authentication  with  IIS  I  get  ’No  Input  file  specified’. 

The  security  model  of  IIS  is  at  fault  here.  This  is  a  problem  common  to  all  CGI  programs  running  under 
IIS.  A  workaround  is  to  create  a  plain  HTML  file  (not  parsed  by  PHP)  as  the  entry  page  into  an 
authenticated  directory.  Then  use  a  META  tag  to  redirect  to  the  PHP  page,  or  have  a  link  to  the  PHP 
page.  PHP  will  then  recognize  the  authentication  correctly.  With  the  ISAPI  module,  this  is  not  a  problem. 
This  should  not  effect  other  NT  web  servers.  For  more  information,  see: 
http://support.microsoft.eom/support/kb/articles/ql60/4/22.asp. 

7.  My  PHP  script  works  on  IE  and  Lynx,  but  on  Netscape  some  of  my  output  is  missing.  When  I  do  a 
"View  Source"  I  see  the  content  in  IE  but  not  in  Netscape. 

Very  good  question!  ;)  This  is  a  tricky  little  issue  and  it  has  come  up  twice  in  the  past  month  as  of  this 
writing.  Both  times  I  ended  up  spending  a  good  20  minutes  trying  to  figure  out  what  the  heck  was  going 
on.  The  answer  is  that  both  IE  and  Lynx  ignore  any  NULs  ( \ 0)  in  the  HTML  stream.  Netscape  does  not. 
The  best  way  to  check  for  this  is  to  compile  the  command-line  version  of  PHP  (also  known  as  the  CGI 
version)  and  run  your  script  from  the  command  line  and  pipe  it  through  ’od  -c’  and  look  for  any  \0 
characters.  (If  you  are  on  Windows  you  need  to  find  an  editor  or  some  other  program  that  lets  you  look  at 
binary  files)  When  Netscape  sees  a  NUL  in  a  file  it  will  typically  not  output  anything  else  on  that  line 
whereas  both  IE  and  Lynx  will.  If  this  issue  has  bitten  you,  congratulations !  You  are  not  alone. 

8.  How  am  I  supposed  to  mix  XML  and  PHP?  It  complains  about  my  <?xml>  tags! 

You  need  to  turn  off  the  short  tags  by  setting  short_tags  to  0  in  your  php .  ini  file,  or  by  using  the 
appropriate  Apache  directive.  You  could  even  use  a  <File>  section  to  do  this  selectively. 

9.  How  can  I  use  PHP  with  FrontPage  or  some  other  HTML  editor  that  insists  on  moving  my  code 
around? 

One  of  the  easiest  things  to  do  is  to  enable  using  ASP  tags  in  your  PHP  code.  This  allows  you  to  use  the 
ASP-style  <%  and  %>  code  delimiters.  Some  of  the  popular  HTML  editors  handle  those  more 
intelligently  (for  now).  To  enable  the  ASP-style  tags,  you  need  to  set  the  asp_tags  php .  ini  variable,  or 
use  the  appropriate  Apache  directive. 
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10.  Where  can  I  find  a  complete  list  of  pre-set  variables  available  to  me,  and  why  are  these  not 
documented  in  the  PHP  documentation? 

The  best  way  is  to  stick  a  <?php  phpinfo  ( )  ;  ?>  part  on  a  page  and  load  it  up.  This  will  show  you  all 
sorts  of  information  about  your  PHP  setup,  including  a  list  of  both  environment  variables  and  also 
special  variables  set  by  your  web  server.  This  list  can’t  really  be  documented  in  the  PHP  documentation 
because  it  will  change  from  one  server  to  another. 

11.  I’m  trying  to  access  one  of  the  standard  CGI  variables  (such  as  $DOCUMENT_ROOT  or 
$HTTP_REFERER)  in  a  user-defined  function,  and  it  can’t  seem  to  find  it.  What’s  wrong? 

Environment  variables  are  normal  global  variables,  so  you  must  either  declare  them  as  global  variables  in 
your  function  (by  using  "global  $document_root;  ",  for  example)  or  by  using  the  global  variable 
array  (ie,  "$globals  [  "document_root"  ] ". 
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PHP  and  HTML  interact  a  lot :  PHP  generate  HTML,  and  HTML  has  informations  that  will  be  sent  to 
PHP 

1.  I’m  trying  to  use  an  <input  type="image">  tag,  but  the  $foo.x  and  $foo.y  variables  aren’t  available. 
Where  are  they? 

When  submitting  a  form,  it  is  possible  to  use  an  image  instead  of  the  standard  submit  button  with  a  tag 
like: 


<input  type="image"  src="image . gif "  name="foo"> 


When  the  user  clicks  somewhere  on  the  image,  the  accompanying  form  will  be  transmitted  to  the  server 
with  two  additional  variables:  foo.x  and  foo.y. 

Because  $foo.x  and  $foo.y  are  invalid  variable  names  in  PHP,  they  are  automagically  converted  to 
$foo_x  and  $foo_y.  That  is,  the  periods  are  replaced  with  underscores. 


2.  How  do  I  create  arrays  in  a  HTML  <form>? 

To  get  your  <form>  result  sent  as  an  array  to  your  PHP  script  you  name  the  <input>,  <select>  or 
<textarea>  elements  like  this: 


<input 

name="MyArray [ ] 

"> 

<input 

name="MyArray [ ] 

"> 

<input 

name="MyArray [ ] 

"> 

<input 

name="MyArray [ ] 

"> 

Notice  the  square  brackets  after  the  variable  name,  that’s  what  makes  it  an  array.  You  can  group  the 
elements  into  different  arrays  by  assigning  the  same  name  to  different  elements: 


<input 

<input 

<input 

<input 


name="MyArray [ ] "> 
name="MyArray [ ] "> 
name="MyOtherArray [ ] "> 
name="MyOtherArray [ ] "> 


This  produces  two  arrays.  My  Array  and  MyOtherArray,  that  gets  sent  to  the  PHP  script. 


Nota:  You  need  not  use  indices  with  arrays  in  HTML,  although  you  can  specify  number  or  associative 
indices,  so  you  can  exactly  specify  what  indices  will  contain  the  information  provided  by  that  input 
element.  If  you  do  not  specify  indices,  the  array  gets  filled  in  the  order  the  elements  appear  in  the 
form. 
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For  functions  you  can  use  to  process  these  arrays  once  you  get  them  into  your  scripts,  please  see  the 
Arrays  section 


3.  How  do  I  get  all  the  results  from  a  select  multiple  HTML  tag? 

The  select  multiple  tag  in  an  HTML  construct  allows  users  to  select  multiple  items  from  a  list.  These 
items  are  then  passed  to  the  action  handler  for  the  form.  The  problem  is  that  they  are  all  passed  with  the 
same  widget  name.  ie. 


<select  name="var"  multiple> 


Each  selected  option  will  arrive  at  the  action  handler  as: 

var=optionl 

var=option2 

var=option3 


Each  option  will  overwrite  the  contents  of  the  previous  $var  variable.  The  solution  is  to  use  PHP’s 
"array  from  form  element"  feature.  The  following  should  be  used: 

<select  name="var[]"  multiple> 


This  tells  PHP  to  treat  $var  as  an  array  and  each  assignment  of  a  value  to  var[]  adds  an  item  to  the  array. 
The  first  item  becomes  $var  [  0  ] ,  the  next  $var  [  1  ] ,  etc.  The  count;)  function  can  be  used  to  determine 
how  many  options  were  selected,  and  the  sort  ')  function  can  be  used  to  sort  the  option  array  if  necessary. 

Note  that  if  you  are  using  JavaScript  the  [  ]  on  the  element  name  might  cause  you  problems  when  you 
try  to  refer  to  the  element  by  name.  Use  it’s  numerical  form  element  id  instead,  or  enclose  the  variable 
name  in  single  quotes  and  use  that  as  the  index  to  the  elements  array,  for  example: 

variable  =  documents . forms [ 0 ]. elements [ ' var [ ] ' ] ; 
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PHP  is  the  best  language  for  web  programing,  but  what  about  other  languages? 

1.  PHP  vs.  ASP? 

ASP  is  not  really  a  language  in  itself,  it’s  an  acronym  for  Active  Server  Pages,  the  actual  language  used 
to  program  ASP  with  is  Visual  Basic  Script  or  JScript.  The  biggest  drawback  of  ASP  is  that  it’s  a 
proprietary  system  that  is  natively  used  only  on  Microsoft  Internet  Information  Server  (IIS).  This  limits 
it’s  availability  to  Win32  based  servers.  There  are  a  couple  of  projects  in  the  works  that  allows  ASP  to  run 
in  other  environments  and  webservers:  InstantASP  (http://www.halcyonsoft.com/prods/iasp/iasp.htm) 
from  Halcyon  (http://www.halcyonsoft.com/)  (commercial).  Chili !Soft  ASP  (http://www.chilisoft.com/) 
from  Chili !Soft  (http://www.chilisoft.com/chiliasp/default.asp)  (commercial)  and  OpenASP  from 
ActiveScripting.org  (http://www.activescripting.org/)  (free).  ASP  is  said  to  be  a  slower  and  more 
cumbersome  language  than  PHP,  less  stable  as  well.  Some  of  the  pros  of  ASP  is  that  since  it  primarily 
uses  VBScript  it’s  relatively  easy  to  pick  up  the  language  if  you’re  already  know  how  to  program  in 
Visual  Basic.  ASP  support  is  also  enabled  by  default  in  the  IIS  server  making  it  easy  to  get  up  and 
running.  The  components  built  in  ASP  are  really  limited,  so  if  you  need  to  use  "advanced"  features  like 
interacting  with  FTP  servers,  you  need  to  buy  additional  components. 

2.  Is  there  an  ASP  to  PHP  converter? 

Yes,  asp2php  (http://asp2php.naken.cc/)  is  the  one  most  often  referred  to. 

3.  PHP  vs.  Cold  Fusion? 

PHP  is  commonly  said  to  be  faster  and  more  efficient  for  complex  programming  tasks  and  trying  out  new 
ideas.  PHP  is  generally  referred  to  as  more  stable  and  less  resource  intensive  as  well.  Cold  Fusion  has 
better  error  handling,  database  abstraction  and  date  parsing  although  database  abstraction  is  addressed  in 
PHP  4.  Another  thing  that  is  listed  as  one  of  Cold  Fusion’s  strengths  is  its  excellent  search  engine,  but  it 
has  been  mentioned  that  a  search  engine  is  not  something  that  should  be  included  in  a  web  scripting 
language.  PHP  runs  on  almost  every  platform  there  is;  Cold  Fusion  is  only  available  on  Win32,  Solaris, 
Linux  and  HP/UX.  Cold  Fusion  has  a  good  IDE  and  is  generally  easier  to  get  started  with,  whereas  PHP 
initially  requires  more  programming  knowledge.  Cold  Fusion  is  designed  with  non-programmers  in 
mind,  while  PHP  is  focused  on  programmers. 

A  great  summary  by  Michael  J  Sheldon  on  this  topic  has  been  posted  to  the  PHP  mailing  list.  A  copy  can 
be  found  here  (http://marc.theaimsgroup.com/?l=php3-general&m=95602167412542&w=l). 


4.  PHP  vs.  Perl? 

The  biggest  advantage  of  PHP  over  Perl  is  that  PHP  was  designed  for  scripting  for  the  web  where  Perl 
was  designed  to  do  a  lot  more  and  can  because  of  this  get  very  complicated.  The  flexibility  /  complexity 
of  Perl  makes  it  easier  to  write  code  that  another  author  /  coder  has  a  hard  time  reading.  PHP  has  a  less 
confusing  and  stricter  format  without  losing  flexibility.  PHP  is  easier  to  integrate  into  existing  HTML 
than  Perl.  PHP  has  pretty  much  all  the  ’good’  functionality  of  Perl:  constructs,  syntax  and  so  on,  without 
making  it  as  complicated  as  Perl  can  be.  Perl  is  a  very  tried  and  true  language,  it’s  been  around  since  the 
late  eighties,  but  PHP  is  maturing  very  quickly. 
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PHP  has  already  a  long  history  behind  him:  Legendary  PHP  1.0,  PHP/FI,  PHP  3.0  and  PHP  4.0. 
1.  Migrating  from  PHP  2  to  PHP  3? 

PHP/FI  2.0  is  no  longer  supported.  Please  see  appropriate  manual  section  for  information  about 
migration  from  PHP/FI  2.0. 

If  you  are  still  working  with  PHP  2,  we  strongly  recommend  you  to  upgrade  straight  to  PHP  4. 
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PHP  has  already  a  long  history  behind  him  :  Legendary  PHP  1.0,  PHP/FI,  PHP  3.0  and  PHP  4.0. 

1.  Migrating  from  PHP3  to  PHP4 

PHP  4  was  designed  to  be  as  compatible  with  earlier  versions  of  PHP  as  possible  and  very  little 
functionality  was  broken  in  the  process.  If  you’re  really  unsure  about  compatibility  you  should  install 
PHP  4  in  a  test  environment  and  run  your  scripts  there. 

Also  see  the  appropriate  migration  appendix  of  this  manual. 


2.  Incompatible  functions? 

Since  PHP  4  is  basically  a  rewrite  of  the  entire  PHP  engine  there  was  very  few  functions  that  were 
altered  and  only  then  some  of  the  more  exotic  ones. 
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There  can  be  some  questions  we  can’t  put  into  other  categories.  Here  you  can  find  them. 

1.  Where  did  the  pop-ups  go  on  the  website?  Can  I  have  the  code  for  that? 

The  yellow  pop-up  windows  on  the  old  site  were  pretty  cool,  but  were  very  difficult  to  maintain  (since 
some  companies  seem  to  enjoy  changing  the  way  their  browsers  work  with  every  new  release). 

All  the  code  for  previous  versions  of  the  website  is  still  available  through  CVS.  Specifically,  the  last 
version  of  shared. inc  (that  had  all  the  Javascript  and  DHTML  to  do  the  popups)  is  available  here 
(http://cvsweb.php.  net/co.php/phpweb/include/shared.inc?r=  1.123). 
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Acerca  de  las  incompatibilidades  en  PHP  3.0 

PHP  3.0  ha  sido  reescrito  desde  cero.  Tiene  un  interprete  propio,  que  es  mucho  mas  robusto  y  consistente 
que  el  de  2.0.  3.0  es  tambien  significativamente  mas  rapido,  y  usa  menos  memoria.  De  cualquier  modo, 
algunas  de  estas  mejoras  no  fueron  posibles  sin  alterar  la  compatibilidad,  tanto  de  sintaxis  como  de 
funcionamiento. 

Ademas,  los  desarrolladores  de  PHP  han  intentado  clarificar  la  sintaxis  y  la  semantica  de  PHP  3.0,  y  eso 
ha  causado  tambien  algunas  incompatibilidades.  Creemos  que,  a  la  larga,  estos  cambios  seran  para  mejor. 

Este  capftulo,  intentara  guiarle  a  traves  de  las  incompatibilidades  que  encontrara  si  migra  de  PHP/FI  2.0 
a  PHP  3.0,  ademas  de  ayudarle  a  resolverlas.  No  se  mencionaran  aquf  las  herramientas  nuevas,  hasta  que 
sea  necesario. 

Existe  un  programa  que  convierte  automaticamente  sus  viejos  guiones  PHP/FI  2.0.  Puede  hallarlo  en  el 
subdirectorio  convertor  de  la  distribucion  3.0  de  PHP  Este  programa,  solo  actua  en  referencia  a  los 
cambios  sintacticos,  asf  que  deberfa  leer  este  capftulo  detenidamente,  de  todos  modos. 


Tags  de  inicio  y  fin 

Probablemente  lo  primero  que  note,  es  que  los  tags  de  inicio  y  fin  de  PHP  han  cambiado.  Las  vieja  forma 
<?  >  ha  sido  reemplazada  por  tres  nuevas  formas  posibles: 

Ejemplo  A-l.  Migracion:  Cambio  de  los  tags  de  inicio  y  fin 

<?  echo  "Esto  es  codigo  PHP/FI  2.0.\n";  > 

Como  en  la  version  2.0,  PHP/FI  tambien  soporta  esta  variante: 

Ejemplo  A-2.  Migracion:  Nuevos  tags  de  inicio  y  fin,  Variante  1 

<?  echo  "Esto  es  codigo  PHP  3.0!\n";  ?> 

Note  que  el  tag  de  fin,  consiste  ahora  en  un  signo  de  interrogation  y  un  mayor-que,  mientras  que  antes 
era  solo  un  mayor-que.  Sin  embargo  si  Ud.  planea  usar  XML  en  su  servidor,  tendra  problemas  con  esta 
nueva  variante,  porque  PHP  tratara  de  ejecutar  las  marcas  en  los  documentos  XML,  como  codigo  PHP. 

Es  por  esto  que  se  han  introducido  las  siguientes  variantes: 

Ejemplo  A-3.  Migracion:  Nuevos  tags  de  inicio  y  fin,  Variante  2 

<?php  echo  "Esto  es  codigo  PHP  3.0!\n";  ?> 

Algunas  personas  han  tenido  problemas  con  editores  que  no  reconocen  del  todo  los  tags  de  instrucciones 
de  procesamiento.  Microsoft  FrontPage  es  uno  de  esos  editores,  y  a  modo  de  remedio,  se  ha  introducido 
tambien  esta  otra  variante: 
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Ejemplo  A-4.  Migration:  Nuevos  tags  de  inicio  y  fin,  Variante  3 

<script  language="php"> 

echo  "Esto  es  codigo  PHP  3.0!\n"; 

</ script> 


sintaxis  de  if..endif 


La  manera  ‘alternativa’  de  escribir  la  declaration  if/elseif/else,  usando  if();elseif();  else;  endif;  no  puede 
implementarse  eficientemente  sin  agregar  una  gran  complejidad  al  interprete  3.0.  Por  eso  la  sintaxis  ha 
cambiado: 


Ejemplo  A-5.  Migracion:  vieja  sintaxis  if..endif 

if  ($foo) ; 

echo  "sip\n"; 
elseif  ( $bar ) ; 

echo  "casi\n"; 
else; 

echo  "nop\n"; 
endif; 


Ejemplo  A-6.  Migracion:  nueva  sitaxis  if..endif  (si... finsi) 

if  ($foo) : 

echo  "sip\n"; 
elseif  ( $bar ) : 

echo  "casi\n"; 
else : 

echo  "nop\n"; 
endif; 

Notese  que  los  punto-y-coma,  han  sido  reemplazados  por  los  los  dos-puntos  en  todas  las  declaraciones, 
excepto  en  la  de  finalization  (endif). 


sintaxis  de  while  (mientras) 

Al  igual  que  para  if.. endif,  la  sintaxis  de  while. .endwhile  se  ha  cambiado: 


Ejemplo  A-7.  Migracion:  vieja  sintaxis  while..endwhile 

while  ($more_to_come) ; 
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endwhile; 

Ejemplo  A-8.  Migration:  nueva  sintaxis  while..endwhile 

while  ($itiore_to_come) : 
endwhile; 


Aviso 

Si  se  utiliza  la  sintaxis  vieja  de  mientras...fin-mientras  en  PHP  3.0,  el  resultado  es 
un  bucle  infinito. 


Tipos  de  expresiones 

PHP/FI  2.0  uso  el  lado  izquierdo  de  las  expresiones  para  determinar  de  que  tipo  debfa  ser  el  resultado. 
PHP  3.0  toma  ambos  lados  en  cuenta  cuando  determina  el  tipo  de  resultado,  y  eso  puede  producir 
resultados  impredecibles  si  ejecuta  guiones  2.0  en  3.0. 

Considere  este  ejemplo: 

$a[0]=5; 

$a[l]=7; 

$key  =  key ($a) ; 
while  (""  !=  $key)  { 
echo  "$keyn"; 
next ( $  a ) ; 

} 

En  PHP/FI  2.0,  esto  mostrana  los  dos  indices  de  $a.  En  PHP  3.0,  no  muestra  nada.  El  motivo  es  que  en 
PHP  2.0,  al  ser  el  argumento  izquierdo  de  tipo  cadena,  se  comparaba  cadenas,  y  puesto  que  ciertamente 
" "  no  es  igual  a  "  0 ",  el  bucle  continua.  En  PHP  3.0,  cuando  se  compara  una  cadena  con  un  entero,  se 
realiza  una  comparacion  de  enteros  (la  cadena  es  convertida  a  entero).  Esto  es  comparar  entonces 
atoi  ( " " )  que  es  0,  y  variablelist  que  tambien  es  0,  y  como  0==0,  el  bucle  no  avanzara. 

La  solution  a  esto  es  simple,  reemplaze  la  declaration  while  con: 

while  (( string) $key  !=  "")  { 
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Cambios  en  los  mensajes  de  error 

Los  mensajes  de  error  de  PHP  3.0  son  usualmente  mas  precisos  que  los  de  2.0,  pero  ya  no  podra  ver  el 
fragmento  de  codigo  que  causo  el  error.  En  vez  de  eso,  se  le  mostrara  el  nombre  de  archivo  y  numero  de 
lfnea  del  error. 


Evaluacion  booleana  por  corto-circuito 

En  PHP  3.0,  la  evaluacion  booleana  es  por  cortocircuito.  Eso  significa  que  en  una  expresion  como  (1  |  I 
prueba_me  ( )  ) ,  la  funcion  prueba_me()  no  sera  ejecutada  ya  que  nada  puede  cambiar  el  resultado  de  la 
expresion  despues  del  1 . 

Si  bien  es  este  un  detalle  menor  de  la  compatibilidad,  puede  provocar  inesperados  efectos  colaterales 


Retorno  de  valores  en  funciones  verdadero/falso 


La  mayoria  de  las  funciones  internas  han  sido  reescritas,  asi  que  devuelven  true  (verdadero)  si  hubo 
exito,  o  false  (falso)  si  hubo  falla,  en  oposicion  a  los  valores  0  y  -1  de  PHP/FI  2.0,  para  identicas 
circunstancias.  La  nueva  respuesta  permite  mas  codigo  logico,  como  $fp  =  fopen  ( "  /su/f  ichero" ) 
or  fail  ( "diablos  ! " )  ; .  Puesto  que  PHP/FI  2.0  no  tiene  reglas  claras  acerca  de  lo  que  devuelven  las 
funciones  cuando  fallan,  scripts  de  este  tipo  deberan  revisarse  manualmente  despues  de  usar  el  conversor 
de  2.0  a  3.0. 


Ejemplo  A-9.  Migracion  desde  2.0:  Valores  de  retorno,  codigo  viejo 

$fp  =  fopen ($file,  "r"); 
if  ($fp  ==  -1) ; 

echo ("No  se  pudo  abrir  el  f ichero  $file  para  su  lectura<br>\n" ) ; 
endif ; 


Ejemplo  A-10.  Migracion  desde  2.0:  Valores  de  retorno,  codigo  nuevo 

$fp  =  @fopen  ($file,  "r")  or  print ("No  se  pudo  abrir  el  fichero  $file  para  su  lec- 
tura<br>\n" ) ; 


Otras  incompatibilidades 


•  El  modulo  Apache  de  3.0  no  soportara  versiones  de  Apache  anteriores  a  la  1.2.  Es  requisito  Apache 
1 .2  o  posterior. 

•  echo  3  no  soportara  las  cadenas  de  formato.  Use  en  su  lugar  la  funcion  printf'). 
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•  En  PHP/FI  2.0,  un  efecto  colateral  en  la  implementacion  hacfa  que  $foo  [  0  ]  tenga  el  mismo  efecto 
que  $foo.  Esto  ya  no  es  asf  en  PHP  3.0. 

•  La  lectura  de  arreglos  con  $  array  [  ]  ya  no  esta  soportada 

Esto  es,  no  se  puede  recorrer  un  arreglo  mediante  un  bucle  que  ejecute  $data  =  $array  [  ] .  Use 
current')  y  next')  en  su  lugar. 

Tambien,  $arrayl  [  ]  =  $array2  no  agrega  los  valores  de  $array2  a  $arrayl,  pero  agrega 
$array2  como  la  ultima  entrada  de  $arrayl.  Vease  tambien  el  soporte  de  arreglos 
multidimensionales . 


•  "  +  "  ya  no  funciona  como  operador  de  concatenation  de  cadenas,  sino  que  convierte  los  argumentos,  a 

numeros,  y  realiza  una  suma  numerica.  Utilize  " . "  en  su  lugar. 

Ejemplo  A-ll.  Migration  desde  2.0:  concatenando  cadenas 

echo  "1"  +  "1"; 

En  PHP  2.0  esto  mostrarfa  1 1,  en  PHP  3.0  serfa  2.  Use  en  su  lugar: 
echo  "  1 " . " 1 " ; 

$a  =  1; 

$b  =  1; 
echo  $a  +  $b; 

Esto  da  2  igualmente  en  PHP  2.0  y  3.0. 

$a  =  1; 

$b  =  1; 
echo  $a.$b; 

Esto  da  11  en  PHP  3.0. 
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What  has  changed  in  PHP  4.0 

PHP  4.0  and  the  integrated  Zend  engine  have  greatly  inproved  PHPs  performance  and  capabilities,  but 
great  care  has  been  taken  to  break  as  little  existing  code  as  possible.  So  migrating  your  code  from  PHP 
3.0  to  4.0  should  be  much  easier  than  migrating  from  PHP/FI  2.0  to  PHP  3.0.  A  lot  of  existing  PHP  3.0 
code  should  be  ready  to  run  without  changes,  but  you  should  still  know  about  the  few  differences  and 
take  care  to  test  your  code  before  switching  versions  in  production  environments.  The  following  should 
give  you  some  hints  about  what  to  look  for. 


Running  PHP  3  and  PHP  4  concurrently 

Recent  operating  systems  provide  the  ability  to  perform  versioning  and  scoping.  This  features  make  it 
possible  to  let  PHP  3  and  PHP  4  run  as  concurrent  modules  in  one  Apache  server. 

This  feature  is  known  to  work  on  the  following  platforms: 

•  Linux  with  recent  binutils  (binutils  2.9. 1.0.25  tested) 

•  Solaris  2.5  or  better 

•  FreeBSD  (3.2,  4.0  tested) 

To  enable  it,  configure  PHP3  and  PHP4  to  use  APXS  (— with-apxs)  and  the  necessary  link  extensions 
(-enable-versioning).  Otherwise,  all  standard  installations  instructions  apply.  For  example: 

$  ./configure  \ 

— with-apxs=/apache/bin/apxs  \ 

— enable-versioning  \ 

— with-mysql  \ 

— enable-track-vars 


Migrating  Configuration  Files 

The  global  configuration  file,  php3  .  ini,  has  changed  its  name  to  php .  ini. 

For  the  Apache  configuration  file,  there  are  slightly  more  changes.  The  MIME  types  recognized  by  the 
PHP  module  have  changed. 

application/x-httpd-php3  — >  application/x-httpd-php 

application/x-httpd-php3-source  — >  application/ x-httpd-php-source 


You  can  make  your  configuration  files  work  with  both  versions  of  PHP  (depending  on  which  one  is 
currently  compiled  into  the  server),  using  the  following  syntax: 
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AddType  application/x-httpd-php3  .php3 

AddType  application/x-httpd-php3-source  .php3s 

AddType  application/x-httpd-php  .php 

AddType  application/x-httpd-php-source  .phps 


In  addition,  the  PHP  directive  names  for  Apache  have  changed. 

Starting  with  PHP  4.0,  there  are  only  four  Apache  directives  that  relate  to  PHP: 

php_value  [PHP  directive  name]  [value] 
php_flag  [PHP  directive  name]  [On | Off] 
php_admin_value  [PHP  directive  name]  [value] 
php_admin_f lag  [PHP  directive  name]  [On | Off] 


There  are  two  differences  between  the  Admin  values  and  the  non  admin  values: 

•  Admin  values  (or  flags)  can  only  appear  in  the  server-wide  apache  configuration  files  (e.g.,  httpd.conf). 

•  Standard  values  (or  flags)  cannot  control  certain  PHP  directives,  for  example  -  safe  mode  (if  you  could 
override  safe  mode  settings  in  .htaccess  files,  it  would  defeat  safe-mode’s  purpose).  In  contrast,  Admin 
values  can  modify  the  value  of  any  PHP  directive. 

To  make  the  transition  process  easier,  PHP  4.0  is  bundled  with  scripts  that  automatically  convert  your 
Apache  configuration  and  .htaccess  files  to  work  with  both  PHP  3.0  and  PHP  4.0.  These  scripts  do  NOT 
convert  the  mime  type  lines !  You  have  to  convert  these  yourself. 

To  convert  your  Apache  configuration  files,  run  the  apconf-conv.sh  script  (available  in  the  scripts/apache/ 
directory).  For  example: 

~/php4 / scripts/apache : #  . / apconf-conv .sh  /usr/local/ apache/ conf /httpd . conf 


Your  original  configuration  file  will  be  saved  in  httpd.conf.orig. 

To  convert  your  .htaccess  files,  run  the  aphtaccess-conv.sh  script  (available  in  the  scripts/apache/ 
directory  as  well): 

~/php4 /scripts/apache : #  find  /  -name  .htaccess  -exec  ./aphtaccess-conv.sh  {}  \; 


Likewise,  your  old  .htaccess  files  will  be  saved  with  an  .orig  prefix. 
The  conversion  scripts  require  awk  to  be  installed. 
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Parsing  and  execution  are  now  two  completely  seperated  steps,  no  execution  of  a  files  code  will  happen 
until  the  complete  file  and  everything  it  requires  has  completely  and  successfully  been  parsed. 

One  of  the  new  requirenments  introduced  with  this  split  is  that  required  and  included  files  now  have  to  be 
syntactically  complete.  You  can  no  longer  spread  the  different  controling  parts  of  a  control  structure 
across  file  boundaries.  That  is  you  cannot  start  a  for  or  while  loop,  an  if  statement  or  a  switch  block 
in  one  file  and  have  the  end  of  loop,  else,  endif,  case  or  break  statements  in  a  different  file. 

It  still  perfectly  legal  to  include  additional  code  within  loops  or  other  control  structures,  only  the 
controling  keywords  and  corresponding  curly  braces  { .  .  . }  have  to  be  within  the  same  compile  unit  (file 
or  eval  ')ed  string). 

This  should  not  harm  to  much  as  spreading  code  like  this  should  be  considered  as  very  bad  style  anyway. 

Another  thing  no  longer  possible,  though  rarely  seen  in  PHP  3.0  code  is  returning  values  from  a  required 
file.  Returning  a  value  from  an  included  file  is  still  possible. 


Error  reporting 

Configuration  changes 

With  PHP  3.0  the  error  reporting  level  was  set  as  a  simple  numeric  value  formed  by  summing  up  the 
numbers  related  to  different  error  levels.  Usual  values  where  15  for  reporting  all  errors  and  warnings  or  7 
for  reporting  everything  but  simple  notice  messages  reporting  bad  style  and  things  like  that. 

PHP  4.0  now  has  a  greater  set  of  different  error  and  warning  levels  and  comes  with  a  configuration  parser 
that  now  allows  for  symbolic  constants  to  be  used  for  setting  up  the  intended  behavior. 

Error  reporting  level  should  now  be  configured  by  explicitly  taking  away  the  warning  levels  you  do  not 
want  to  generate  error  messages  by  x-oring  them  from  the  symbolic  constant  e_all.  Sounds 
complicated?  Well,  lets  say  you  want  the  error  reporting  system  to  report  all  but  the  simple  style 
warnings  that  are  categorized  by  the  symbolic  constant  e_notice.  Then  you’ll  put  the  following  into 
your  php .  ini:  error_reporting  =  E_ALL  &  ~  (  E_N0TICE  ).  If  you  want  to  suppress  warnings 
too  you  add  up  the  appropriate  constant  within  the  braces  using  the  binary  or  operator  ’I’: 
error_reporting=  E_ALL  &  ~  (  E_NOTICE  |  E_WARNING  )  . 
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Aviso 

Using  the  old  values  7  and  1 5  for  setting  up  error  reporting  is  a  very  bad  idea  as 
this  suppresses  some  of  the  newly  added  error  classes  including  parese  errors. 
This  may  lead  to  very  strange  behavior  as  scripts  might  no  longer  work  without 
error  messages  showing  up  anywhere. 

This  has  lead  to  a  lot  of  unreproduceable  bug  reports  in  the  past  where  people 
reported  script  engine  problems  they  were  not  capable  to  track  down  while  the 
true  case  was  usually  some  missing  ’}’  in  a  required  file  that  the  parser  was  not 
able  to  report  due  to  a  misconfigured  error  reporting  system. 

So  checking  your  error  reporting  setup  should  be  the  first  thing  to  do  whenever 
your  scripts  silently  die.  The  Zend  enginge  can  be  considererd  mature  enough 
nowadays  to  not  cause  this  kind  of  strange  behavior. 


Additional  warning  messages 

A  lot  of  existing  PHP  3.0  code  uses  language  constructs  that  should  be  considered  as  very  bad  style  as 
this  code,  while  doing  the  intended  thing  now,  could  easily  be  broken  by  changes  in  other  places.  PHP 
4.0  will  output  a  lot  of  notice  messages  in  such  situations  where  PHP  3.0  didn’t.  The  easy  fix  is  to  just 
turn  off  E_NOTICE  messages,  but  it  is  usually  a  good  idea  to  fix  the  code  instead. 

The  most  common  case  that  will  now  produce  notice  messages  is  the  use  of  unquoted  string  constants  as 
array  indices.  Both  PHP  3.0  and  4.0  will  fall  back  to  interprete  theese  as  strings  if  no  keyword  or 
constant  is  known  by  that  name,  but  whenever  a  constant  by  that  name  had  been  defined  anywhere  else  in 
the  code  it  might  break  your  script.  This  can  even  become  a  security  risk  if  some  intruder  manages  to 
redefine  string  constants  in  a  way  that  makes  your  script  give  him  access  rights  he  wasn’t  intended  to 
have.  So  PHP  4.0  will  now  warn  you  whenever  you  use  unquoted  string  constants  as  for  example  in 
$HTTP_SERVER_VARS  [REQUEST_METHOD  ]  .  Changing  it  to 

$http _ SERVER_VARS  [ '  request_method '  ]  will  make  the  parser  happy  and  greatly  improve  the  style 

and  security  of  your  code. 

Another  thing  PHP  4.0  will  now  tell  you  about  is  the  use  of  uninitialized  variables  or  array  elements. 


Initializers 


Static  variable  and  class  member  initializers  only  accept  scalar  values  while  in  PHP  3.0  they  accepted 
any  valid  expression.  This  is,  once  again,  due  to  the  split  between  parsing  and  execution  as  no  code  has 
yet  been  executed  when  the  parser  sees  the  initializer. 

For  classes  you  should  use  constructors  to  initialize  member  variables  instead.  For  static  variables 
anything  but  a  simple  static  value  rarely  makes  sense  anyway. 
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empty  ("0") 

The  perhaps  most  cotroversal  change  in  behavior  has  happend  to  the  behavior  of  the  empty  ').  A  String 
containing  only  the  character  ’0’  (zero)  is  now  considered  empty  while  it  wasn’t  in  PHP  3.0. 

This  new  behavior  makes  sense  in  web  applications,  with  all  input  fields  returning  strings  even  if 
numeric  input  is  requested,  and  with  PHP’s  capabilities  of  automatic  type  conversion.  But  on  the  other 
had  it  might  break  your  code  in  a  rather  subtle  way,  leading  to  misbehavior  that  is  hard  to  track  down  if 
you  do  not  know  about  what  to  look  for. 


Missing  functions 

While  PHP  4.0  comes  with  a  lot  of  new  features,  functions  and  extensions,  you  may  still  find  some 
functions  from  version  3.0  missing.  A  small  number  of  core  functions  has  vanished  because  they  do  not 
work  with  the  new  scheme  of  splitting  parsing  and  execution  as  introduced  into  4.0  with  the  Zend 
engine.  Other  functions  and  even  complete  extensions  have  become  obsolete  as  newer  functions  and 
extensions  serve  the  same  task  better  and/or  in  a  more  general  way.  Some  functions  just  simply  haven’t 
been  ported  yet  and  finally  some  functions  or  extensions  may  be  missing  due  to  license  conflicts. 


Functions  missing  due  to  conceptual  changes 

As  PHP  4.0  now  seperates  parsing  from  execution  it  is  no  longer  possible  to  change  the  behavior  of  the 
parser  (now  embedded  in  the  Zend  engine)  at  runtime  as  parsing  already  happend  by  then.  So  the 
function  short_tags()  has  ceased  to  exist.  You  can  still  change  the  parsers  behavior  by  setting 
appropriate  values  in  the  php .  ini  file. 

Another  feature  from  PHP  3.0  that  didn’t  make  it  into  4.0  is  the  experimental  debugging  interface  as 
described  in  ???  in  this  manual.  A  seperate  true  debuger  is  promissed  to  be  released  as  a  Zend  product 
but  hasn’t  become  visible  yet. 


Deprecate  functions  and  extensions 

The  Adabas  and  Solid  database  extensions  are  no  more.  Long  live  the  unified  ODBC  extension  instead. 


Changed  status  for  unset() 

unset)),  although  still  available,  is  implemented  a  literal  different  in  PHP  4.0  so  that  it  no  longer  counts 
as  a  ’real’  function. 

This  has  no  direct  consequences  as  the  behavior  of  unset))  didn’t  change,  but  testing  for  "unset"  usign 
function_exists))  will  return  false  as  it  would  with  othern  lowlevel  functions  like  echo)). 

Another  more  practical  change  is  that  it  is  no  longer  possible  to  call  unset))  indirectly,  that  is 

$func="unset " ;  $func  ($somevar)  won’t  work  anymore. 
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Extensions  written  for  PHP  3.0  will  not  work  with  PHP  4.0  anymore,  neither  as  binaries  nor  at  the  source 
level.  It  is  not  to  difficult  to  port  your  extensions  to  PHP  4.0  if  you  have  access  to  the  original  sources.  A 
detailed  description  of  the  actual  porting  process  is  not  part  of  this  text  (yet). 


Variable  substitution  in  strings 

PHP  4.0  adds  a  new  mechanism  to  variable  substitution  in  strings.  You  can  now  finally  access  object 
member  variables  and  elements  from  multidimensional  arrays  within  strings. 

To  do  so  you  have  to  enclose  your  variables  with  curly  braces  with  the  dollar  sign  immediately  following 
the  opening  brace:  {$...} 

To  embed  the  value  of  an  object  member  variable  into  a  string  you  simply  write  "text 
{  $ob  j->member }  text"  while  in  PHP  3.0  you  had  to  use  something  like  "text 
" . $ob j->member . "  text". 

This  should  lead  to  more  readable  code,  while  it  may  break  existing  scripts  written  for  PHP  3.0.  But  you 
can  easily  check  for  this  kind  of  problem  by  checking  for  the  character  combination  { $  in  your  code  and 
by  replacing  it  with  \  { $  with  your  favourite  search-and-replace  tool. 


Cookies 


PHP  3.0  hat  the  bad  habit  of  setting  cookies  in  the  reverse  order  of  the  setcookie')  calls  in  your  code. 
PHP  4.0  breaks  with  this  habbit  and  creates  the  cookie  header  lines  in  exactly  the  same  order  as  you  set 
the  cookies  in  the  code. 

This  might  break  some  existing  code,  but  the  old  behaviour  was  so  strange  to  understand  that  it  deserved 
a  change  to  prevent  further  problems  in  the  future. 
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Anadiendo  funciones  al  PHP3 

Prototipo  de  Funcion 

Todas  las  funciones  son  como  esta: 

void  php3_algo ( INTERNAL_FUNCTION_PARAMETERS )  { 

} 


Incluso  si  su  funcion  no  lleva  argumentos,  es  asf  como  se  le  llama. 


Argumentos  de  Funcion 

Los  argumentos  son  siempre  de  tipo  pval.  Este  tipo  contiene  una  union  que  es  el  tipo  actual  del 
argumento.  A  si.  si  su  funcion  tiene  dos  argumentos,  debera  hacer  algo  como  lo  que  sigue  al  principio  de 
la  misma: 


Ejemplo  C-l.  Extrayendo  argumentos  de  funcion 

pval  *argl,  *arg2; 

if  (ARG_COUNT (ht )  !=  2  | |  getParameter s (ht , 2 , Sargl , &arg2 ) ==FAILURE )  { 
WRON  G_P  ARAM_C  OUN  T ; 

} 


NOTA:  Los  argumentos  pueden  pasarse  tanto  por  valor  como  por  referenda.  En  ambos  casos,  necesitara 
pasar  &(pval  *)  a  getParameters.  Si  desea  comprobar  si  el  enesimo  parametro  le  ha  sido  enviado  o  no  por 
referenda,  puede  utilizar  la  funcion  ParameterPassedByReference(ht,n).  Esta  devolvera  16  0,  segun 
corresponda. 

Cuando  cambie  alguno  de  los  parametros  pasados,  tanto  si  son  enviados  por  referencia  o  por  valor,  puede 
volver  a  comenzar  con  este  llamando  la  funcion  pval_destructor  sobre  el  mismo,  o,  si  es  una  ARRAY  a  la 
que  quiere  anadir  algo,  puede  utilizar  funciones  similares  a  las  incluidas  en  internal_functions.h,  que 
manipulan  el  valor  return_value  como  si  fuera  de  tipo  ARRAY. 

Ademas,  si  cambia  un  parametro  a  IS_STRING,  asegurese  primero  de  asignar  el  valor  y  el  tamano  a  la 
cadena  creada  por  estrdupO  y  solo  entonces  cambiar  su  tipo  a  IS_STRING.  Si  modifica  la  cadena  de  un 
parametro  que  ya  es  IS_STRING  o  IS_ARRAY,  debera  primero  aplicarle  la  funcion  pval_destructor. 


Argumentos  de  Funcion  Variables 

Una  funcion  puede  tomar  un  numero  variable  de  argumentos.  Si  su  funcion  puede  tomar  tanto  2  como  3 
argumentos,  utilice  el  siguiente  codigo: 
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Ejemplo  C-2.  Argumentos  de  funcion  variables 

pval  *argl,  *arg2,  *arg3; 
int  arg_count  =  ARG_COUNT (ht ) ; 

if  (arg_count  <  2  | |  arg_count  >  3  | | 

getParameters (ht, arg_count, &argl, &arg2,  &arg3) ==FAILURE)  { 
WRONG_PARAM_COUNT ; 

} 


Usando  los  Argumentos  de  Funcion 

El  tipo  de  cada  argumento  se  guarda  en  el  campo  type  del  pval.  Este  tipo  puede  ser: 


Tabla  C-l.  Tipos  Intemos  de  PHP 


1S STRING 

Cadena 

1S D0UBLE 

Coma  flotante  de  doble  precision 

!S LONG 

Entero  largo 

1S ARRAY 

Matriz 

1S EMPTY 

Nada 

lS USER FUNCTION 

?? 

lS_INTERNAL_FUNCTION 

??  (N.D.:  si  alguno  de  estos  no  se  puede  pasar  a  una 
funcion,  borrese) 

1S CLASS 

?? 

!S_OBJECT 

?? 

Si  obtiene  un  argumento  de  un  tipo  y  desea  utilizarlo  como  si  fuera  de  otro,  o  si  quiere  forzar  a  que  un 
argumento  sea  de  un  tipo  determinado,  puede  usar  una  de  las  siguientes  funciones  de  conversion: 

convert_to_long (argl ) ; 
convert_to_double (argl) ; 
convert_to_string (argl) ; 

convert_to_boolean_long (argl ) ;  /*  Si  la  cadena  es  ""  o  "0"  pasa  a  ser  0;  si  no, 
convert_string_to_number (argl) ;  /*  Convierte  la  cadena  a  LONG  o  a  DOUBLE,  de- 

pendiendo  de  su  contenido  */ 


Estas  funciones  convierten  el  valor  in-situ.  No  devuelven  nada. 

El  argumento  real  es  almacenado  en  una  union  cuyos  miembros  son: 


vale  1  */ 
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•  IS_STRING:  argl-> value. str.val 

•  IS_LONG:  argl->value.lval 

•  IS_DOUBLE:  argl->value.dval 


Manejo  de  Memoria  en  las  Funciones 

La  memoria  necesitada  por  una  funcion  debera  ser  asignada  usando  emalloc()  o  estrdupO.  Estas  son 
funciones  abstractas  de  manejo  de  memoria  que  son  similares  a  las  funciones  normales  malloc()  y 
strdupO-  La  memoria  debera  liberarse  con  efree(). 

Hay  dos  tipos  de  memoria  en  este  programa:  la  memoria  que  se  devuelve  al  troceador  (parser)  en  una 
variable,  y  la  memoria  que  se  necesita  para  almacenamiento  temporal  de  datos  en  sus  funciones.  Cuando 
asigne  una  cadena  a  una  variable  que  se  devolvera  al  troceador  debera  asegurarse  previamente  de  asignar 
la  memoria  con  emalloc()  o  con  estrdup().  Esta  memoria  NUNCA  debe  ser  liberada  por  usted,  salvo  si 
mas  adelante,  en  la  misma  funcion,  sobreescribe  la  asignacion  original  (aunque  este  habito  de 
programacion  no  es  bueno). 

Para  cada  trozo  de  memoria  temporal/permanente  que  precise  en  sus  funciones/librerfa  debera  utilizar  las 
funciones  emalloc(),  estrdupO,  y  efree().  Estas  se  comportan  EXACTAMENTE  como  sus  funciones 
equivalentes.  Cualquier  cosa  que  asigne  con  emalloc()  o  estrdupO  debera  liberarla  con  efree()  en  uno  u 
otro  momento,  salvo  que  se  suponga  que  deba  permanecer  activa  hasta  el  final  del  programa;  de  otro 
modo,  se  producira  una  fuga  de  memoria.  El  significado  de  "estas  se  comportan  exactamente  como  sus 
funciones  equivalentes"  es:  si  llama  a  efreef)  sobre  algo  que  no  ha  sido  asignado  previamente  con 
emalloc()  o  con  estrdupO,  puede  provocar  un  fallo  de  segmentation.  Por  ello  debe  tener  cuidado  y  liberar 
toda  la  memoria  desperdiciada. 

Si  compila  con  "-DDEBUG",  el  PHP3  mostrara  una  lista  de  toda  la  memoria  que  fue  asignada  usando 
emallocf)  y  estrdupO,  Pero  que  nunca  fue  liberada  con  efree(),  al  terminar  de  ejecutar  el  guion 
especificado. 


Asignando  Variables  en  la  Tabla  de  Sfmbolos 

Estan  disponibles  una  serie  de  macros  que  hacen  mas  facil  el  asignar  una  variale  en  la  tabla  de  sfmbolos: 


•  SET_VAR_STRING(nombre,valor)  1 

•  SET_VAR_DOUBLE(nombre,  valor) 

•  SET_VAR_LONG(nombre,  valor) 


Las  tablas  de  sfmbolos  en  PHP  3.0  se  implementan  como  tablas  hash  (con  extracto).  En  todo  momento, 
&symbol_table  es  un  puntero  a  la  tabla  de  sfmbolos  ’principal’,  mientras  que  active_symbol_table 
apunta  a  la  tabla  de  sfmbolos  activa  (pueden  ser  identicas,  al  principio  de  todo,  o  diferentes,  si  se  esta 
dentro  de  una  funcion). 
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Los  ejemplos  siguientes  utilizan  ’active_symbol_table’.  Debera  reemplazarla  por  &symbol_table  si 
desea  trabajar  especfficamente  con  la  tabla  de  sfmbolos  ’principal’.  Tambien  se  pueden  aplicar  las 
mismas  funciones  a  matrices,  como  se  explica  mas  abajo. 


Ejemplo  C-3.  Comprobando  si  $algo  existe  en  una  tabla  de  sfmbolos 

if  (hash_exists (active_symbol_table, " algo" , sizeof ( "algo" )) )  {  existe...  } 

else  {  no  existe  } 


Ejemplo  C-4.  Hallando  el  tamano  de  una  variable  en  una  tabla  de  sfmbolos 

hash_f ind (active_symbol_table, "algo" , sizeof ( "algo" )  ,  Svalptr) ; 
check (valptr . type) ; 


Las  matrices  en  PHP  3.0  se  implementan  utilizando  las  mismas  tablas  hash  que  para  las  tablas  de 
sfmbolos.  Elio  quiere  decir  que  las  dos  funciones  anteriores  se  pueden  usar  tambien  para  comprobar 
variables  dentro  de  matrices. 

Si  desea  definir  un  nuevo  sfmbolo  de  matriz  en  una  tabla  de  sfmbolos,  debera  hacer  lo  que  sigue. 

Primero,  debera  comprobar  si  ya  existe  usando  hash_exists()  o  hash_find()  y  abortar  la  ejecucion  de 
forma  apropiada. 

Luego  inicialice  la  matriz: 


Ejemplo  C-5.  Inicializando  una  nueva  matriz 

pval  matriz; 

if  (array_init (Smatriz)  ==  FAILURE)  {  fallo...  } ; 

hash_update (act ive_symbol_t able, "algo" , sizeof ( "algo" ) , Smatriz , sizeof (pval ) , NULL) 


Este  codigo  declara  una  nueva  matriz,  llamada  $algo,  en  la  tabla  de  sfmbolos  activa.  Esta  matriz  esta 
vacfa. 

Ahora  se  muestra  como  anadirle  elementos: 


Ejemplo  C-6.  Anadir  entradas  a  una  nueva  matriz 

pval  elemento; 

elemento . type  =  IS_LONG; 
elemento . value . lval  =  5; 

/*  define  $algo["bar"]  =  5  */ 

hash_update (matriz . value . ht , "bar " , sizeof ( "bar " ) , S elemento, sizeof (pval ) , NULL) ; 
/*  define  $algo[7]  =  5  */ 

hash_index_update (matriz . value . ht , 7 , selemento, sizeof (pval ) , NULL) ; 
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/*  define  el  siguiente  puesto  libre  en  $algo[], 

*  $algo[8],  como  5  (funciona  como  en  php2) 

*/ 

hash_next_index_insert (matriz . value . ht , Selemento,  sizeof (pval )  ,  NULL)  ; 


Si  desea  modificar  un  valor  que  ha  insertado  en  una  matriz  asociativa,  debera  primero  extraerlo  de  ella. 
Para  evitar  esa  sobrecarga,  puede  pasarle  un  puntero  pval  **  a  la  funcion  para  insertar  en  una  matriz 
asociativa,  y  sera  actualizada  con  la  direccion  pval  *  del  elemento  insertado  dentro  de  la  matriz.  Si  dicho 
valor  es  null  (como  en  todos  los  ejemplos  anteriores),  el  parametro  se  ignora. 

hash_next_index_insert()  usa  mas  o  menos  la  misma  logica  que  "$algo[]  =  bar;"  en  el  PHP  2.0. 

Si  esta  preparando  una  matriz  como  valor  devuelto  por  una  funcion,  puede  inicializar  la  misma  como 
antes,  haciendo: 

if  (array_init (return_value)  ==  FAILURE)  {  f alio . . . ;  } 


...  y  luego  anadiendole  valores  con  las  funciones  auxiliares: 

add_next_index_long (return_value, val_long) ; 
add_next_index_double (return_value, val_double) ; 
add_next_index_string (return_value,  estrdup (val_cadena) )  ; 


Por  supuesto,  si  la  adicion  no  se  realiza  justo  despues  de  inicializar  la  matriz,  probablemente  tenga  que 
buscarla  antes: 

pval  *matriz; 

if  (hash_find (active_symbol_table, "algo" , sizeof ( "algo" ) , (void  ** ) smatriz ) ==FAILURE)  {  no  se 
else  {  usar  matriz->value . ht . . .  } 


Notese  que  hash_find  recibe  un  puntero  a  un  puntero  a  pval,  y  no  un  puntero  a  pval. 

Casi  cualquier  funcion  de  matrices  asociativas  devuelve  SUCCESS  o  FAILURE  (excepto  por 
hash_exists(),  que  devuelve  un  valor  logico  de  certeza). 


Devolviendo  valores  simples 

Estan  disponibles  varias  macros  para  facilitar  la  devolution  de  valores  de  una  funcion. 
Todas  las  macros  RETURN_*  fijan  el  valor  y  retornan  de  la  funcion: 

•  RETURN 

•  RETURN_FALSE 

•  RETURN_TRUE 
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•  RETURN_LONG(l) 

•  RETURN_STRING(s,dup)  Si  dup  es  true,  duplica  la  cadena 

•  RETURN_STRINGL(s,l,dup)  Devuelve  la  cadena  (s)  especificando  el  largo  (1). 

•  RETURN_DOUBLE(d) 


Las  macros  RETVAL_*  fijan  el  valor,  pero  no  retoman. 

•  RETVAL_FALSE 

•  RETVAL_TRUE 

•  RETVAL_LONG(l) 

•  RETVAL_STRING(s,dup)  Si  dup  es  true,  duplica  la  cadena 

•  RETVAL_STRINGL(s,l,dup)  Devuelve  la  cadena  (s)  especificando  el  largo  (1). 

•  RETVAL_DOUBLE(d) 


Las  macros  anteriores  haran  un  estrdupO  del  argumento  ’s’,  de  modo  que  puede  liberal'  con  seguridad  el 
argumento  despues  de  llamar  a  la  macro,  o,  alternativamente,  utilizar  memoria  asignada  estaticamente. 

Si  su  funcion  devuelve  respuestas  logicas  de  exito/error,  use  siempre  RETURN_TRUE  y 
RETURN_FALSE  respectivamente. 


Devolviendo  valores  complejos 

Su  funcion  tambien  puede  devolver  un  tipo  de  datos  complejo,  tal  como  un  objeto  o  una  matriz. 
Devolviendo  un  objeto: 

1.  Llame  a  object_init(retum_value). 

2.  Rellenela  con  valores.  Las  funciones  disponibles  para  ello  son  listadas  mas  abajo. 

3.  Posilemente  registre  funciones  para  este  objeto.  Para  obtener  valores  del  objeto,  la  funcion  debera 
de  obtener  "this”  desde  la  active_symbol_table.  Su  tipo  debera  ser  IS_OBJECT,  y  basicamente  se 
trata  de  una  matriz  asociativa  estandar  (es  decir,  que  podra  usar  funciones  de  matriz  asociativa  sobre 
. value. ht).  El  registro  en  sf  de  la  funcion  se  puede  hacer  utilizando: 

add_method (  return_value,  nombre_func,  puntero_func  ); 


Las  funciones  utilizadas  para  rellenar  un  objeto  son: 

•  add_property_long(  return_value,  nombre_propiedad,  1 )  -  Anade  una  propiedad  llamada 
’nombre_propiedad’,  de  tipo  long,  y  con  valor  T 

•  add_property_double(  return_value,  nombre_propiedad,  d  )  -  Igual,  pero  anadiendo  un  double 
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•  add_property_string(  return_value,  nombre_propiedad,  cad  )  -  Igual,  pero  aiiadiendo  una  cadena 

•  add_property_stringl(  return_value,  nombre_propiedad,  cad,  1 )  -  Igual,  pero  aiiadiendo  una  cadena  de 
longitud  T 

Devolviendo  una  matriz: 

1 .  Llame  a  array _init(return_value). 

2.  Rellenela  con  valores.  Las  funciones  disponibles  para  ello  son  listadas  mas  abajo. 

Las  funciones  utilizadas  para  rellanar  una  matriz  son: 

•  add_assoc_long(return_value,clave,l)  -  anade  un  elemento  asociativo  con  clave  ’clave’  y  valor  long  T 

•  add_assoc_double(return_value,clave,d) 

•  add_assoc_string(return_value,clave,cad,duplicar) 

•  add_assoc_stringl(return_value,clave,cad,largo,duplicar)  -  especifica  el  largo  de  la  cadena 

•  add_index_long(return_value,indice,l)  -  anade  un  elemento  en  la  posicion  ’indice’  con  valor  long  T 

•  add_index_double(return_value,indice,d) 

•  add_index_string(return_value,indice,cad) 

•  add_index_stringl(return_value,indice,cad,largo)  -  especifica  el  largo  de  la  cadena 

•  add_next_index_long(return_value,l)  -  anade  un  elemento  a  la  matriz  en  la  proxima  posicion  libre  con 
valor  long  T 

•  add_next_index_double(return_value,d) 

•  add_next_index_string(return_value,c  ad) 

•  add_next_index_stringl(return_value,cad,largo)  -  especifica  el  largo  de  la  cadena 


Usando  la  lista  de  recursos 

El  PHP  3.0  tiene  una  forma  estandarizada  de  tratar  con  distintos  tipos  de  recursos.  Esto  sustituye  a  las 
listas  enlazadas  locales  del  PHP  2.0. 

Funciones  disponibles: 

•  php3_list_insert(ptr,  tipo)  -  devuelve  el  ’id’  del  recurso  recien  insertado 

•  php3_list_delete(id)  -  borra  el  recurso  con  el  id  especificado 

•  php3_list_find(id,*tipo)  -  devuelve  el  puntero  al  recurso  con  el  id  especificado,  y  actualiza  ’tipo’  al 
tipo  del  mismo 

Estas  funciones  se  utilizan  tfpicamente  para  controladores  SQL,  pero  pueden  utilizarse  para  cualquier 
otra  cosa,  como,  por  ejemplo,  para  mantener  descriptores  de  archivo. 
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El  codigo  tfpico  de  un  lista  serfa  como  este: 


Ejemplo  C-7.  Anadiendo  un  nuevo  recurso 

RESOURCE  ‘recurso; 

/*  ...asignar  memoria  para  el  recurso  y  adquirirlo . . .  */ 

/*  anadir  un  recurso  a  la  lista  */ 

return_value->value . lval  =  php3_list_insert ( (void  *)  recurso,  LE_RESOURCE_TYPE) 
return_value->type  =  IS_LONG; 


Ejemplo  C-8.  Utilizando  un  recurso  existente 

pval  *id_recurso; 

RESOURCE  ‘recurso; 
int  tipo; 

convert_to_long (id_recurso) ; 

recurso  =  php3_list_f ind (id_recurso->value . lval,  &tipo) ; 
if  (tipo  ! =  LE_RESOURCE_TYPE )  { 

php3_error (E_WARNING, "el  recurso  numero  %d  tiene  el  tipo  equivocado" , id_recurso 
>value . lval ) ; 

RETURN_FALSE; 

} 

/*  ...usar  recurso...  */ 


Ejemplo  C-9.  Borrando  un  recurso 

pval  *id_recurso; 

RESOURCE  ‘recurso; 
int  tipo; 

convert_to_long (id_recurso) ; 
php3_list_delete ( id_recurso->value . lval ) ; 


Los  tipos  de  recursos  deben  registrarse  en  php3_list.h,  en  la  enumeration  list_entry_type.  Ademas,  hay 
que  anadir  codigo  de  desconexion  para  cada  tipo  de  recurso  definido  en  la  funcion  list_entry_destructor() 
de  list.c  (incluso  si  no  hay  nada  que  hacer  para  la  desconexion,  debera  anadir  un  caso  vacio). 


Utilizando  la  tabla  de  recursos  persistentes 

El  PHP  3.0  tiene  una  forma  estandar  de  almacenar  recursos  persistentes  (es  decir,  recursos  que  se 
mantienen  entre  accesos).  El  primer  modulo  que  utilizo  esta  caracterfstica  fue  el  MySQL  y  tras  el  fue  el 
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mSQL,  asf  que  uno  puede  hacerse  una  buena  idea  de  como  utilizar  un  recurso  persistente  leyendo 
mysql.c.  Las  funciones  a  revisar  son: 

php3_mysql_do_connect 

php3_mysql_connect() 

php3_mysql_pconnect() 

La  idea  general  de  los  modulos  persistentes  es: 

1 .  Codifique  todos  sus  modulos  para  que  funcionen  con  la  lista  regulares  de  recursos  mencionadas  en 
la  seccion  (9). 

2.  Codifique  funciones  extra  de  conexion  que  comprueben  si  el  recurso  ya  esta  en  la  lista  de  recursos 
persistentes.  Si  ya  esta,  regfstrelo  en  la  lista  regular  como  un  puntero  a  la  lista  de  recursos 
persistentes  (debido  a  L,  el  resto  del  codigo  debera  funcionar  de  inmediato).  Si  no  esta  en  la  lista, 
creelo,  anadalo  a  la  lista  de  recursos  persistentes  Y  anada  un  puntero  al  mismo  desde  la  lista  regular 
de  recursos.  Asi  todo  el  codigo  funcionara  porque  esta  en  la  lista  regular,  pero  en  la  siguiente 
conexion  el  recurso  ya  estara  en  la  lista  persistente  y  podra  ser  usado  sin  re-crearlo.  Debera  registrar 
estos  recursos  con  un  tipo  diferente  (por  ejemplo,  LE_MYSQL_LINK  para  el  enlace  no  persistente 
y  LE_MYSQL_PLINK  para  un  enlace  persistente). 


Si  se  leyera  mysql.c,  notarfa  que,  salvo  por  que  hay  una  funcion  de  conexion  mas  compleja,  no  hay  que 
cambiar  nada  mas  del  resto  del  modulo. 

Existe  exactamente  la  misma  interfaz  para  la  lista  de  recursos  regular  y  para  la  lista  de  recursos 
persistente,  pero  cambiando  unicamente  ’lista’  por  ’listap’: 

•  php3_plist_insert(ptr,  tipo)  -  devuelve  el  ’id’  del  recurso  recien  insertado 

•  php3_plist_delete(id)-  borra  el  recurso  con  el  id  especificado 

•  php3_plist_find(id,*tipo)  -  devuelve  el  puntero  al  recurso  con  el  id  especificado,  y  actualiza  ’tipo’  al 
tipo  del  mismo 

Sin  embargo,  es  mas  que  probable  que  estas  funciones  se  muestren  inutiles  cuando  intente  implementar 
un  modulo  persistente.  Tfpicamente  usted  querra  usar  el  hecho  de  que  la  tabla  de  recursos  persistentes  es 
en  realidad  una  matriz  asociativa.  Por  ejemplo,  en  los  modulos  MySQL/mSQL,  cuando  hay  una  llamada 
a  pconnect()  (conexion  persistente),  la  funcion  combina  en  una  cadena  el  servidor/usuario/clave  que  se 
pasaron  a  la  funcion  y  codifica  el  enlace  SQL  con  esta  cadena  como  clave.  La  siguiente  vez  que  alguien 
llame  a  pconnect()  con  el  mismo  servidor/usuario/clave,  se  generara  la  misma  clave,  y  la  funcion  hayara 
el  enlace  SQL  en  la  lista  persistente. 

Hasta  que  se  documente  mejor,  debera  mirar  en  mysql.c  o  en  msql.c  para  ver  como  utilizar  las 
capacidades  de  matriz  asociativa  de  la  listap. 

Una  cosa  importante:  a  los  recursos  que  van  a  parar  a  la  lista  de  recursos  persistentes  *NO*  se  les  debe 
asignar  memoria  usando  el  gestor  de  memoria  del  PHP,  es  decir,  que  NO  deben  ser  creados  utilizando 
emalloc()  o  estrdup(),  etc.  En  este  caso  se  debe  usar  las  funciones  habituales  malloc(),  strdup(),  etc.  La 
razon  para  esto  es  simple:  al  final  de  la  peticion  (final  del  acceso),  se  borran  todos  los  trozos  de  memoria 
asignados  con  el  gestor  de  memoria  del  PHP.  Como  la  lista  persistente  se  supone  que  no  se  debe  borrar  al 
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final  de  una  peticion,  no  se  debe  utilizar  el  gestor  de  memoria  del  PHP  para  asignar  memoria  a  los 
recursos  de  la  misma. 

Cuando  registre  un  recuros  que  vaya  a  estar  en  la  lista  persistente,  debera  anadir  destructores  tanto  a  la 
lista  persistente  como  a  la  no  persistente.  El  destructor  de  la  lista  no  persistente  no  debera  hacer  nada.  El 
de  la  lista  persistente  debera  liberar  adecuadamente  los  recursos  obtenidos  por  dicho  tipo  (por  ejemplo, 
memoria,  enlaces  SQL,  etc.).  Tal  y  como  pasa  para  los  recursos  no  persistentes,  DEBERA  anadir 
destmctores  para  cada  recurso  aunque  no  sean  necesarios  y  esten  vacfos.  Recuerde  que  como  no  se 
pueden  usar  emallocf)  y  similares  en  conjuncion  con  la  lista  persistente,  tampoco  podra  utilizar  efree() 
aquf. 


Anadiendo  directivas  de  configuracion  en  tiempo  de  ejecucion 

Muchas  de  las  caracterfsticas  del  PHP3  pueden  ser  configuradas  en  tiempo  de  ejecucion.  Estas  directivas 
de  configuracion  pueden  aparecer  tanto  en  el  fichero  php3.ini  o,  en  el  caso  de  la  version  de  modulo  del 
Apache,  en  los  archivos  .conf  del  propio  Apache.  La  ventaja  de  tenerlos  en  los  archivos  .conf  del  Apache 
es  que  se  puden  configurar  directorio  por  directorio.  Esto  quiere  decir  que  cada  uno  puede  tener  un  cierto 
safemodeexecdir,  por  ejemplo,  mientras  otro  directorio  puede  tener  otro.  Esta  granularidad  en  la 
configuracion  es  especialmente  util  cuando  un  servidor  soporta  multiples  servidores  virtuales. 

Los  pasos  necesarios  para  anadir  una  nueva  directiva: 

1.  Anada  la  directiva  a  la  estructura  php3_ini_structure  en  mod_php3.h. 

2.  En  main.c,  edite  la  funcion  php3_module_startup  y  anada  la  llamada  a  cfg_get_string()  o  a 
cfg_get_long()  segun  se  requiera. 

3.  Anada  la  directiva,  las  restricciones  y  un  comentario  a  la  estructura  php3_commands  en 
mod_php3.c.  Cuidado  con  la  parte  de  restricciones.  Las  de  tipo  RSRC_CONF  solo  puede  aparecer 
en  los  archivos  .conf  del  Apache.  Las  directivas  de  tipo  OR_OPTIONS  pueden  aparecer  en  cualquier 
parte,  incluso  en  los  habituales  archivos  .htaccess. 

4.  Anada  el  elemento  apropiado  para  su  directiva,  bien  en  php3takelhandler(),  bien  en 
php3flaghandler(). 

5.  Necesita  anadir  su  nueva  directiva  a  la  seccion  de  configuracion  de  la  funcion  _php3_info()  en 
functions/info. c. 

6.  Y  finalmente,  por  supuesto,  debera  utilizar  su  nueva  directiva  en  algun  sitio.  Estara  accesible  como 
php3_ini. directiva. 


Llamando  a  Funciones  del  Usuario 

Para  llamar  a  funciones  del  usuario  desde  una  funcion  interna,  debera  usar  la  funcion 

call_user_function() . 

call_user_function()  devuelve  SUCCESS  si  tiene  exito  y  FAILURE  en  caso  de  que  la  funcion  no  sea 
hallada.  ;  Debera  comprobar  ese  valor  de  retorno!  Si  devuelve  SUCCESS,  debe  usted  ocuparse  de 
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destruir  el  pval  devuelto  (o  devolverlo  como  el  valor  de  retorno  de  su  funcion).  Si  devuelve  FAILURE,  el 
valor  de  valret  no  esta  definido  y  no  debe  tocarlo. 

Todas  las  funciones  internas  que  llaman  a  funciones  de  usuario  deben  ser  reentrantes.  Entre  otras  cosas, 
esto  quiere  decir  que  no  se  utilicen  variables  globales  ni  estaticas. 

call_user_function()  lleva  6  argumentos: 


HashTable  *tabla  funciones 


Esta  es  la  matriz  asociativa  en  la  que  se  buscara  la  funcion. 


pval  *objeto 

Este  es  un  puntero  a  un  objeto  sobre  el  que  se  invoca  la  funcion.  Debera  valer  null  si  se  llama  a  una 
funcion  global.  Si  no  es  null  (es  decir,  si  apunta  a  un  objeto),  el  argumento  tabla_funciones  se  ignora  y 
se  toma  su  valor  a  partir  de  la  codificacion  del  objeto.  El  objeto  *puede*  ser  modificado  por  dicha 
funcion  (esta  accede  a  el  a  traves  de  $this).  Si  por  alguna  razon  no  desea  que  eso  ocurra,  envfe  entonces 
una  copia  del  objeto. 


pval  *nombre_func 

El  nombre  de  la  funcion  a  llamar.  Debe  ser  un  pval  de  tipo  IS_STRING,  con  nombre_func.str.val  y 
nombre_func.str.len  fijados  a  los  valores  apropiados.  El  nombre_func  es  modificado  por 
call_user_function(),  que  lo  convierte  a  minusculas.  Si  necesita  preservar  el  nombre,  envfe  una  copia  del 
mismo. 


pval  *valret 

Un  puntero  a  una  estructura  pval,  en  la  que  se  guarda  el  valor  de  returno  de  la  funcion.  Hay  que  asignar 
espacio  a  la  estructura  previamente,  porque  la  funcion  call_user_function()  NO  lo  asigna  por  sf  misma. 


int  num  params 

El  numero  de  parametros  que  se  pasan  a  la  funcion. 


pval  *params[] 

Una  matriz  de  punteros  a  los  valores  que  se  pasaran  como  argumentos  a  la  funcion.  El  primer  argumento 
esta  en  el  elemento  0,  el  segundo  en  el  elemento  1,  etc.  La  matriz  es  una  matriz  de  punteros  a  pval.  Los 
punteros  se  envfan  tal  cual  a  la  funcion,  lo  que  quiere  decir  que  si  la  funcion  modifica  sus  argumentos,  se 
modifican  los  valores  originales  (paso  por  referenda).  Si  no  desea  ese  comportamiento,  pase  una  copia. 
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Para  informar  de  errores  desde  una  funcion  interna,  debera  llamar  la  funcion  php3_error().  Esta  lleva  al 
menos  dos  parametros:  el  primero  el  es  nivel  del  error,  y  el  segundo  es  la  cadena  de  formato  para  el 
mensaje  de  error  (como  en  una  llamada  estandar  a  printf')).  Cualquiera  de  los  argumentos  siguientes  son 
para  la  cadena  de  formato.  Los  niveles  de  error  son: 


ENOTICE 

Por  defecto  se  visualizan  las  noticas,  e  indican  que  el  guion  encontro  algo  que  podrfa  indicar  un  error, 
pero  que  tambien  podrfa  ocurrir  durante  el  curso  normal  de  la  ejecucion  del  mismo.  Por  ejemplo,  al 
intentar  acceder  al  valor  de  una  variable  que  no  ha  sido  fijado,  o  llamar  a  stat'j  sobre  un  fichero  que  no 
existe. 


E_WARNING 

Por  defecto  se  visualizan  los  avisos,  pero  no  se  interrumpe  la  ejecucion  del  guion.  Estos  indican  un 
problema  que  debiera  haberse  interceptado  en  el  guion  antes  de  la  llamada.  Por  ejemplo,  llamar  ereg  ) 
con  una  expresion  regular  no  valida. 


E_ERROR 

Por  defecto  se  visualizan  los  errores  y  la  ejecucion  del  guion  se  detiene  cuando  la  funcion  retorna.  Estos 
indican  errores  irrecuperables,  como  un  problema  de  asignacion  de  memoria. 


E_PARSE 

Los  errores  de  troceo  solo  debe  generarlos  el  troceador.  El  codigo  se  lista  aquf  con  objeto  de  ser 
exhaustivos. 


E_CORE_ERROR 

Este  es  similar  al  E_ERROR,  pero  generado  por  el  nucleo  del  PHP.  Las  funciones  no  deben  generar  este 
tipo  de  error. 


E_CORE_WARNING 

Este  es  similar  al  E_WARNING,  pero  generado  por  el  nucleo  del  PHP.  Las  funciones  no  deben  generar 
este  tipo  de  error. 

Nota:  "N.D.:"  significa  Nota  del  Documentador  y  es  un  texto  interno 
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Notas 


Tenga  cuidado  aquf.  El  valor  a  usar  se  debe  asignar  dinamicamente  y  de  forma  manual,  pues  el  codigo  de 
manejo  de  memoria  intentara  liberal'  este  puntero  mas  adelante.  Nunca  pase  memoria  asignada  de  forma 
estatica  a  SET_VAR_STRING. 
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Usando  el  Debugger 

El  debugger  interno  de  PHP  es  util  para  localizar  fallos  que  se  resisten.  El  debugger  funciona 
conectandose  a  un  puerto  TCP  cada  vez  que  PHP  comienza.  Todos  los  mensajes  de  error  de  esa  peticion 
seran  enviados  a  esta  conexion  TCP  Esta  informacion  se  entiende  que  que  es  para  un  "servidor  de 
debugger"  que  puede  ejecutarse  en  un  IDE  o  en  un  editor  programabler  (como  Emacs). 

Como  poner  en  marcha  el  debugger: 

1.  Establezca  un  puerto  TCP  para  el  debugger  en  el  archivo  de  configuration  ( debugger.port )  y 
activelo  (debugger.enabled). 

2.  Ponga  en  marcha  un  modulo  de  escucha  de  TCP  en  algun  sitio  (por  ejemplo  socket  -1  -s  1400  en 
UNIX). 

3.  En  su  codigo,  ejecute  "debugger_on(hos  t)",  donde  host  es  la  direccion  IP  o  el  nombre  de  el  host 
ejecutando  un  modulo  de  escucha  de  TCP. 

Ahora,  todos  los  avisos,  notificaciones,  etc.  se  mostraran  en  ese  modulo  de  escucha,  incluso  si  lo  ha 
desactivado  con  error_reporting'). 


Protocolo  del  debugger 

El  protocolo  del  debugger  esta  basado  en  llneas.  Cada  lfnea  tiene  un  tipo,  y  varias  Knea  componen  un 
mensaje.  Cada  mensaje  comienza  con  una  lfnea  del  tipo  start  y  termina  con  una  lfnea  del  tipo  end. 
PHP  puede  enviar  lfneas  para  diferentes  mensajes  simultaneamente. 

Una  lfnea  tiene  este  formato: 

fecha  hora  host(pid)  tipo:  datos  del  mensaje 


fecha 


Fecha  en  formato  ISO  8601  ( aaaa-mm-dd ) 


hora 


Hora  incluyendo  microsegundos:  hh:mm:uuuuuu 


host 


Nombre  DNS  o  direccion  IP  del  host  donde  el  script  de  error  fue  generado. 


pid 


PID  (id  proceso)  en  el  host  del  proceso  en  que  el  script  de  PHP  genero  este  error. 
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tipo 

Tipo  de  la  lfnea.  Dice  al  programa  programa  que  recibe  que  debe  considerar  los  datos  siguientes 
como: 

Tabla  D-l.  Tipos  de  lfnea  del  debugger 


Nombre 

Significado 

start 

Informa  al  programa  que  recibe  que  un  mensaje 
del  debugger  comienza  aqui.  El  contenido  de 
data  sera  el  tipo  del  mensaje  de  error,  listados 
debajo. 

message 

El  mensaje  de  error  de  PHP. 

location 

Nombre  del  fichero  y  numero  de  lfnea  donde 
ocurrio  el  error.  La  primera  lfnea  con  location 
siempre  contendra  la  localization  de  mayor  nivel. 
data  contendra  fichero:  lines.  Siempre 
habra  una  lfnea  de  tipo  location  despues  de 
message  y  despues  de  cada  function. 

frames 

Numero  de  marcos  en  la  pila.  Si  hay  cuatro 
marcos,  espere  information  sobre  los  cuatro 
niveles  de  las  funciones  llamadas.  Si  no  hay  una 
lfnea  de  tipo  "frames",  la  profundidad  se  asume 
que  es  0  (el  error  ocurrio  en  el  nivel  superior). 

function 

Nombre  de  la  funcion  donde  ocurrio  el  error.  Sera 
repetida  una  vez  por  cada  nivel  en  la  pila  de 
funciones. 

end 

Informa  al  programa  que  recibe  que  el  mensaje 
del  debugger  termina  aqui. 

data 

Lfnea  de  datos. 


Tabla  D-2.  Tipos  de  error  del  debugger 


Debugger 

PHP  Internal 

warning 

E WARNING 

error 

E ERROR 

parse 

E PARSE 

notice 

E NOTICE 

core-error 

E CORE ERROR 

core-warning 

E CORE WARNING 

unknown 

(any  other) 
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Ejemplo  D-l.  Ejemplo  de  mensaje  del  debugger 


1998-04-05 

1998-04-05 

1998-04-05 

1998-04-05 

1998-04-05 

1998-04-05 

1998-04-05 


23:27 :400966  lucifer.guardian.no(2048 1 ) 
23:27 :400966  lucifer.guardian.no(2048 1 ) 
23:27 :400966  lucifer.guardian.no(2048 1 ) 
23:27 :400966  lucifer.guardian.no(2048 1 ) 
23:27 :400966  lucifer.guardian.no(2048 1 ) 
23:27 :400966  lucifer.guardian.no(2048 1 ) 
23:27 :400966  lucifer.guardian.no(2048 1 ) 


start:  notice 

message:  Uninitialized  variable 
location:  (null):7 
frames:  1 
function:  display 

location:  /home/ssb/public_html/test.php3: 10 
end:  notice 
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Here  is  the  list  of  PHP  reserved  words,  usual  constants  and  predefined  variables.  You  won’t  find  any 
function  here,  but  rather  language  constructs.  You  shouldn’t  try  to  use  those  names  as  variables,  function, 
constant  or  method’s  name,  as  it  will  surely  lead  to  confusion. 

•  and 

•  $argv 

•  $argc 

•  break 

•  case 

•  class 

•  continue 

•  default 

•  do 

•  die'). 

•  echo  3. 

•  else 

•  elseif 

•  empty')- 

•  endfor 

•  endforeach 

•  endif 

•  endswitch 

•  endwhile 

•  E_ALL 

•  E_PARSE 

•  e_error 

•  E_WARNING 

•  exit(). 

•  extends 

•  FALSE 

•  for 

•  foreach 

•  function 

•  $HTTP_COOKIE_VARS 

•  $HTTP_GET_VARS 

•  $HTTP_POST_VARS 
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•  $$HTTP_POST_FILES 

•  $http_env_vars 

•  $HTTP_SERVER_VARS 

•  if 

•  include ;). 

•  include_once '). 

•  global 

•  list;). 

•  new 

•  not 

•  NULL. 

•  or 

•  parent. 

•  PHP_OS 

•  $PHP_SELF 

•  PHP_VERS  ION 

•  print(). 

•  require;). 

•  require_onceO. 

•  return 

•  static 

•  switch 

•  stdClass 

•  $this 

•  TRUE 

•  var 

•  xor 

•  virtual;). 

•  while 

•  _ FILE _ 

•  _ LINE _ 

•  _ sleep. 

•  _ wakeup. 
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The  following  is  a  list  of  functions  which  create,  use  or  destroy  PHP  resources.  The  function 
is_resource()  can  be  used  to  determine  if  a  variable  is  a  resource  and  get_resource_type()  will  return 
the  type  of  resource  it  is. 


Tabla  F-l.  Resource  Types 


Resource  Type 
Name 

Created  By 

Used  By 

Destroyed  By 

Definition 

aspell 

aspell_new ') 

aspell_check '), 
aspell_check_raw '), 
aspell_suggestO 

None 

Aspell  dictionary 

bzip2 

bzopen') 

bzerrno  ),  bzerror'), 

bzcloseO 

Bzip2  file 

bzerrstr3,  bzflush(), 
bzread3,  bzwritej) 

COM 

com_load  3 

com_invoke 

com_propgetO, 

com_get'), 

com_propput'), 

com_setO, 

com_propput') 

None 

COM  object 
reference 

VARIANT 
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Resource  Type 
Name 


cpdf 


Created  By 


cpdf_open) 


Used  By 


Destroyed  By 


cpdf_close  3 


eO, 


ng3, 

g{)> 

3, 


ng'), 


cpdf_page_init'), 

cpdf_finalize_page ') 
cpdf_finalize  [), 

cpdf_output_buffer') 

cpdf_save_to_file  [), 
cpdf_set_current_pa^i 
cpdf_begin_text  {), 
cpdf_end_text '), 
cpdf_showO, 
cpdf_show_xyO, 
cpdf_text'), 
cpdf_set_fontO, 

cpdf_set_leading  3, 
cpdf_set_text_rendeiji 
cpdf_set_horiz_scaliji 
cpdf_set_text_rise '), 
cpdf_set_text_matrix 
cpdf_set_text_pos(), 
cpdf_set_text_pos(), 
cpdf_set_word_spaci 
cpdf_continue_text ') 
cpdf_stringwidth  3, 
cpdf_save  3, 
cpdf_translate(), 
cpdf_restore(), 

cpdf_scale  3, 

cpdf_rotate(), 
cpdf_setflat3, 
cpdf_setlinejoin'), 
cpdf_setlinecap  3, 
cpdf_setmiterlimit  3, 

cpdf_setlinewidth'), 

cpdf_setdash  3, 
cpdf_moveto  3, 

cpdf_rmoveto  3, 
cpdf_curveto'), 
cpdf_lineto'), 
cpdf_rlinetoO, 

cpdf_circle  3, 
cpdf_arc(), 
cpdf_rect  3, 
cpdf_closepath'3, 
cpdf_stroke  3, 

cpdf_closepath_fill_^trokeO, 
cpdf_fill_stroke3, 
cpdf_clip  3, 
cpdf_fill  3, 
cpdf_setgray_fill'), 
cpdf_setgray_stroke' 
cpdf_setgray(), 
cpdf_setrgbcolor_fill 
cpdf_setrgbcolor_stn 
cpdf_setrgbcolor3. 


I). 

), 

)ke(), 


Definition 


PDF  document  with 
CPDF  lib 
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Resource  Type 
Name 


Created  By 


Used  By 


Destroyed  By 


Definition 


cpdf  outline 
curl 


curl_init ') 


curlinit'), 
curl exec') 


curl_close() 


Curl  session 


dbm 


dbmopen  3 


dba 


dba_popen') 


dba  persistent 


dba_open ) 


dbase 


dbase_open') 


dbmexists'), 

dbmfetch '), 
dbminsert'), 
^lbmreplace  3, 
dbmdeleteO, 
^bmfirstkey'), 
^lbmnextkey  {) 

|  dba_delete(), 

^lba_exists  3, 

[jba_fetch3, 
^ba_firstkey(), 
^ba_insert'), 
^ba_nextkey'), 
^lba_optimize'3, 
^lba_replace  3, 
^lba_sync  3 
|  dba_delete'), 
^lba_exists  3, 
^lba_fetch3, 
^ba_firstkey'), 
^ba_insert'), 
^ba_nextkey(), 
^lba_optimize'3, 
^lba_replace  3, 
^lba_sync  3 


dbmclose  3 


Link  to  DBM 
database 


dba_close  3 


Link  to  DBA  base 


None 


Persistent  link  to 
DBA  base 


|  dbase_pack'), 

^lb  ase_add_rec  ord  > ) , 

|d  base_rcpl  ace_reconjl 
(tl  b  ase_d  c  I  e  te_rec  o  rd 
[dbase_get_record  3, 

|d  base_get_record_w 

^lbase_numfieldsO, 

dbase_numrecords'3 


dbase_close() 


Link  to  Dbase  base 


3, 


th_names'3, 


dbx link object 
dbx result object 


dbx connect() 

dbx_query  3 


dbx_querv  3 

0 


dbx close') 
None 


dbx  connection 
dbx  result 


domxml  attribute 


domxml  document 


domxml  node 


xpath  context 
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Resource  Type 
Name 

Created  By 

Used  By 

Destroyed  By 

Definition 

xpath  object 

fbsql  database 

fbsql_select_db ') 

0 

None 

fbsql  database 

fbsql  link 

fb- 

fbsql_close ') 

Link  to  fbsql 

sql_change_user'), 

fbsql_autocommit'), 

database 

lbsql_connect') 

fb- 

sql_change_user  [), 
fbsql_create_db(), 
fbsql_data_seek(), 
fbsql_db_query '), 
fbsql_drop_db(),  (), 
fbsql_select_db 
fbsql_errno'), 
fbsql_error(), 

fbsql_insert_id'(), 

fbsql_list_dbs() 

fbsql  plink 

fb- 

None 

Persistent  link  to 

sql_change_user'), 

fbsql_autocommitO, 

fbsql  database 

Ibsqlpcon  fleet) 

fb- 

sql_change_user  [), 

fbsql_create_db'), 
fbsql_data_seek ), 

fbsql_db_query  [), 

tbsql  drop  db '),  (), 

fbsql_select_db '), 

fbsql_errno'), 

fbsql_error'), 

fbsql_insert_idO. 

fbsql_list_dbsO 
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Resource  Type 
Name 


Created  By 


Used  By 


Destroyed  By 


Definition 


fbsql  result 


fbsql_db_query '), 
fbsql_list_dbs '), 
fbsql_queryO, 
fbsql_list_fields'), 
fbsql_list_tables '), 
fbsql_tablenameO 


fdf 


fdf_open ') 


tbsql_frce_result ') 


fb- 

sql_affected_rowsO, 
fbsql_fetch_array '), 

fbsql_fetch_assoc'), 
fbsql_fetch_field'), 
fb- 

jsql_fetch_lengths '), 
|fbsql_fetch_object(), 
|fbsql_fetch_row '), 
|fbsql_field_flags  J, 
|fbsql_field_name'), 
jfbsql_field_lenj), 
|tbsql_field_seek  ), 
jfbsql_field_table(), 
|fbsql_field_type '), 
|fbsql_next_result  t), 
|fbsql_num_fieldsi'), 
jfbsql_num_rows'), 
|fbsql_resultO, 
jfbsql_num_rows') 

|  fdf_create  3, 

|fdf_save'), 
jfdf_get_value '), 

|fdf_set_value'), 

|f d  f_  n  e  x  t_fi  e  I  d_n  a  m  e ' ) , 

jfdf_set_ap'), 

fdf_set_status  3, 
jfdf_get_statusO, 
jfdf_set_fileO, 
fdf_get_file  [), 

fdf_set_flags(), 
fdf_set_opt(), 
IdfsetsubmitforiliactionO, 
fdf_set  _javascript_t  ction() 


fbsql  result 


fdf_close') 


FDF  File 


1240 


Apendice  F.  PFIP  Resource  Types 


Resource  Type 
Name 

Created  By 

Used  By 

Destroyed  By 

Definition 

ftp 

ftp_connectO 

ftp_login '), 
ftp_pwd'), 
ftp_cdup"), 
ftpchd  ir '), 

ftp_mkdirO, 

ftp_rmdir'j, 

ftp_nlist'), 

ftp_rawlist(), 

ftp_systype(), 

ftp_pasv(),  ftp_get(), 

ftp_fget(),  ftp_pup), 

ftp_fput;), 

ftp_size'), 

ftp_mdtm '), 

ftp_renatne'j, 

ftp_delete(), 

ftp_site() 

ftp_quit() 

FTP  stream 
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Resource  Type 
Name 

Created  By 

Used  By 

Destroyed  By 

Definition 

gd 

imagecreate  [),  im- 

imagearc '), 

imagedestroyO 

GD  Image 

agecreatefromgifO, 

imagecreate- 

fromjpegO, 

imagecreate- 

frompng(), 

imagecreate- 

fromwbmpO, 

imagecreatefrom- 

stringO, 

imagecreatetrue- 

color() 

imagechar'), 
imagecharupO,  im- 
agecolorallocateO, 
imagecolorat"), 
imagecolorclosest '), 
imagecolorexact  Q, 
i  m  agee  olorresolve ') , 
imagegammacor- 
rect(), 

imagegammacor- 

rect(), 

imagecolorset '),  im- 

agecolorsforindex(), 

imagecolorstotal '), 

imagecolortranspar- 

ent ),  imagecopyO, 

imagecopyresizedO, 

imagedashedlineO, 

imagefill  3,  image- 

filledpolygonO, 

imagefilledrectan- 

glel), 

imaged  II  tohorder'), 

imagegifv), 

imagepngO, 

imagejpegO, 

imagewbmpO, 

imageinterlaceO, 

imageline '), 

imagepolygon'), 

imagepstext(), 

imagerectangle  {), 

imagesetpixeli), 

imagestringO, 

imagestringup'), 

imagesx'), 

imagesyO, 

imagettftextO, 

imagefilledarc(), 

imageellipse(), 

imagefilledellipseO, 

imagecolorcloses- 

talphaO, 

imagecolorexactal- 

pha(), 

imagecolorre- 

solvealpha(), 

imagecopymergeO, 

imagecopy- 

mergegrayO, 

imagecopyresam- 

pled(). 
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Resource  Type 
Name 

Created  By 

Used  By 

Destroyed  By 

Definition 

gd  font 

imageloadfont ') 

imagecharO, 

imagecharupO, 

imagefontheightO 

None 

Font  for  GD 

gd  PS  encoding 

gd  PS  font 

imagepsloadfont ') 

imagepstextO, 

imagepsfreefontO 

PS  font  for  GD 

imagepsslantfont(), 

imagepsextend- 

font(), 

imagepsencode- 

font;), 

imagepsbbox() 
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Resource  Type 
Name 

Created  By 

Used  By 

Destroyed  By 

Definition 

GMP  integer 

gmp_init|p 

gmp_intval(), 
gmp_strval '), 
gmpadd'), 
gmp_sub'), 
gmp_mulp, 
gmp_div_qp, 
gmp_div_r'), 
gmp_div_qrp, 
gmp_div  p, 
gmp_mod'), 
gmp_divexact '), 
gmp_cmpO, 
gmp_neg '), 
gmp_abs  p, 
gmp_sign '), 
gmp_fact(), 
gmp_sqrt  P, 
gmp_sqrtrmP, 
gmp_perfect_square 
gmppowP, 
gmp_powmP, 
gmp_prob_primeP, 
gmp_gcdp, 
gmp_gcdext  P, 
gmp_invertp, 
gmplegendrc  p, 
gmpjacobi'P, 
gmp_randomP, 
gmp_andp, 
gmp_oi'P, 
gmp_xoi'P, 
gmp_setbitp, 
gmp_clrbit'), 
gmp_scan00, 
gmp_scanlp, 
gmp_popcountp, 
gmp_hamdistp 

None 

), 

GMP  Number 
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Resource  Type 
Name 

Created  By 

Used  By 

Destroyed  By 

Definition 

hyperwave 

hw_cp  3, 

hw_children '), 

hw_deleteobject  3 

Hyperwave  object 

document 

hw_docby anchor 3, 

hw_getremote'), 

hw_childrenobj '), 
hw_getparentsO, 

hw_getremotechildrt 

h>3_getparentsobj'), 

hw_getchildcoll'), 

hw_getchildcollobj  3 

hw_getremote'), 

hw_getsrcby  destobj  >' 

hw_getandlock  3, 

hw_gettext  3, 

hw_getobjectbyquer; 

hw_getobjectbyquer; 

hw_getchilddoccoll' 

hw_getchilddoccollo 

hw_getanchorsO, 

hw_getanchorsobj'), 

hw_inscoll\), 

hw_pipedocument  3, 
hw_unlock3 

'COll'3, 

'collobj'), 

5j[3. 
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Resource  Type 
Name 


Created  By 


Used  By 


Destroyed  By 


Definition 


hyperwave  link 


hw_connect ') 


hw_children '), 
hw_childrenobj  Q, 

hw_cp3, 

hw_deleteobject(), 

hw_docby  anchor '), 

hw_docbyanchorobj 

hw_errormsg'), 

hw_edittext'), 

|hw_erroi\), 

|hw_getparents'), 

|hw_getparentsobj(), 

|hw_getchildcoll'), 

|hw_getchildcollobj  3 
|hw_getremote(), 
|hw_getremotechildre 
|hw_getsrcbydestobj' 

|hw_getobject3, 

|hw_getandlock  3, 
|hw_gettext '), 
|hw_getobjectbyquer 
|hw_getobjectbyquer; 
|hw_getobjectbyquer; 
|hw_getobjectbyquer; 
|hw_getchilddoccoll 
|hw_getchilddoccollo|h 
|hw_getanchors'3, 
|hw_getanchorsobj'), 
|hw_mv  3, 
|hw_incollections  3, 

|hw_info(), 

|hw_inscoll'), 

|hw_insdoc  3, 
|hw_insertdocument(' 

|hw_insertobject'3, 

|hw_mapid'), 

|hw_modifyobject  3, 

fiw_pipedocument  3, 

|hw_unlock3, 

|hw_who'3, 

|hw_getusemameO 


hw_close  3, 
hw_free_document  3 


), 


Link  to  Hyperwave 
server 


n3. 


0, 

obj  3, 

■^coll  3, 

collobj'3, 


>J0. 
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Resource  Type 
Name 

Created  By 

Used  By 

Destroyed  By 

Definition 

hyperwave  link 
persistent 

hw_pconnectO 

hw_children '), 
hw_childrenobj '), 
hw_cp3, 

hw_deleteobjectO, 

hw_docby  anchor '), 
hw_docby  anchorobj  \ 
hw_errormsg'), 
hw_edittext'), 
hw_error(), 

hw_getparents'), 

hw_getparentsobjO, 

hw_getchildcoll(), 

hw_getchildcollobj  ') 

hw_getremote(), 

hw_getremotechildre 

hw_getsrcbydestobj' 

hw_getobject3, 

hw_getandlock  [), 

hw_gettext '), 

hw_getobjectbyquer; 

hw_getobjectbyquer; 

hw_getobjectbyquer; 

hw_getobjectbyquer; 

hw_getchilddoccoll' 

hw_getchilddoccollo 

hw_getanchorsO, 

hw_getanchorsobj'), 

hw_mv3, 

hw_incollections  3, 

hw_info'), 
hw_inscoll'), 
hw_insdoc '), 
hw_insertdocument' 
hw_insertobject(), 
hw_mapid(), 
hw_modifyobject  3, 
hw_pipedocument  3, 
hw_unlock'), 

hw_who'), 

hw_getusemame') 

None 

), 

nD, 

0, 

'obj  [), 

'CO  11 '), 

'collobjO, 

3j0, 

Persistent  link  to 
Hyperwave  server 
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Resource  Type 
Name 


Created  By 


leap 


i cap_o pen  3 


imap 


imapopen ') 


Used  By 


Destroyed  By 


icap_fetch_eventO, 
icap_list_events '), 
icap_store_event  3, 
icap_snooze'), 

icap_list_alarms '), 

icap_delete_eventO 

imapappend), 

imap_body  [), 

irnapcheck'j, 
imaporeatemailbox' 
imap_delete'), 
imap_deletemailbox' 
imap_expunge '), 
imap_fetchbody '), 
imap_fetchstructure' 
imap_headerinfo(), 
imap_header'), 
imap_headers  3, 
imap_listmailbox '), 
imap_getmailboxes  3 . 
imap_get_quota(), 

imap_statusO, 

imap_listsubscribed ' 

imap_set_quota(), 

imap_set_quota(), 

irnap_getsubscribed ' 
imap_mailoopy  3, 
i  rnap_mai  l_move '  j, 
imap_num_msg  3, 
imap_num_recent '), 

imap_ping  3, 

imap_renamemailbo; 
imap_reopen  3, 
imap_subscribe  3, 
imap_undeleteO, 
imap_unsubscribe'), 
imap_scanmailbox  3, 
i  rnap_mai  I  boxmsgi  nf 

imap_fetchheader3, 
imap_uid  3, 
imap_msgno'3, 
imap_search  3, 

imap_fetchovervie 


icapoloseO 


imapolose  3 

), 

), 

I, 


t), 


:o0, 


w() 


Definition 


Link  to  icap  server 


Link  to  IMAP,  POP3 
server 
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Resource  Type 
Name 

Created  By 

Used  By 

Destroyed  By 

Definition 

imap  chain 
persistent 

imap  persistent 

ingres 

ingres_connect') 

ingres_queryO, 

ingres_close') 

Link  to  ingresll  base 

ingres_num_rows'), 
ingres_num_fields '), 
ingres_field_name '), 
ingres_field_type'), 
in- 

gresfieldnullable) 

in- 

gres_field_length '), 
in- 

gres_field_precision ' 
ingres_field_scale '), 
in- 

gres_fetch_array'), 

ingres_fetch_rowO, 

in- 

gres_fetch_ohject), 

ingres_rollback 

ingres_commitO. 
ingres_autocommit ') 

), 
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Resource  Type 
Name 

Created  By 

Used  By 

Destroyed  By 

Definition 

ingres  persistent 

ingres_pconncct') 

ingres_query'), 

None 

Persistent  link  to 

ingres_num_rows'), 
ingres_num_fields '), 
ingres_field_name  {), 
ingres_field_type(), 
in- 

gres_field_nullableO 

in- 

gres_field_length '), 
in- 

gres_field_precision ' 
ingres_field_scale '), 
in- 

gres_fetch_array(), 

ingres_fetch_row(), 

in- 

gres_fetch_object '), 

ingres_rollback'), 
ingres_commitO. 
ingres_autocommit  3 

), 

ingresll  base 

interbase  blob 

interbase  link 

ibase_connect() 

ibase_query'). 

ibase_closeO 

Link  to  Interbase 

ibase_prepare  3, 

ibase trans() 

database 

interbase  link 
persistent 

ibase_pconnectO 

ibase_query'), 
ibase_prepare  3, 

ibase trans() 

None 

Persistent  link  to 

Interbase  database 

interbase  query 

ibase_prepare ') 

ibase executeO 

ibase_free_query  3 

Interbase  query 

interbase  result 

ibase_query  3 

ibase_fetch_row  3, 

ibase_free_result'3 

Interbase  Result 

ibase_fetch_object( 

ibase_field_info(), 

ibase_num_fields() 

interbase  transaction 

ibase_trans() 

ibase_commit() 

ibase_rollback() 

Interbase  transaction 

java 
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Resource  Type 
Name 

Created  By 

Used  By 

Destroyed  By 

Definition 

Idap  link 

ldap_connect'), 

ldap_close') 

Idap  connection 

ldap_search ') 

ldap_count_entries ') 
ldap_first_attribute') 
ldap_first_entry '), 
ldap_get_attributes') 

ldap_get_du  ), 
ldap_get_entriesO, 

ldap_get_values '), 
ldap_get_values_len' 
ldap_next_attribute() 
ldap_next_entry ') 

), 

Idap  result 

Idapread') 

ldap_add'), 

ldap_free_result') 

Idap  search  result 

ldap_compare(), 

Idapbind '), 
ldap_count_entries ') 
Idapdclete), 
ldap_errno '), 
ldap_error), 
ldap_first_attribute') 
ldap_first_entry '), 
ldap_get_attributes() 

ldap_get_dn' ), 
ldap_get_entriesO, 

ldap_get_values  [), 

ldap_get_values_leu 

ldap_get_option(), 

ldap_list'), 

ldap_modify(), 

ldap_mod_add 

ldap_mod_replace  3, 

ldap_next_attribute') 

ldap_next_entry'), 

ldap_mod_del '), 

ldap_set_option(), 

ldap_unbind ') 

), 

Idap  result  entry 
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Resource  Type 
Name 

Created  By 

Used  By 

Destroyed  By 

Definition 

meal 

mcal_openO, 

mcal_popen() 

mcal_create_calend 

mcal_rename_calen 

mcal_rename_calen 

mcal_delete_calend 

mcal_fetch_event'), 

mcal_list_events'), 

me  al_append_event( 
me  al_s  tore_event ' ) , 
mcal_delete_event '), 
mcal_list_alarms  [), 
mcal_event_init '), 
me  al_e  vent_s  et_c  ate 
me  al_e  vent_s  et_title 
me  al_e  vent_s  et_de  sc 
mcal_event_set_start 
mcal_event_set_end' 
me  al_e  vent_s  et_alari 
mcal_event_set_clas 
me  al_next_rec  urrenc 
me  al_e  vent_s  et_recu 
mcal_event_set_recu 
me  al_e  vent_s  et_recu 

mcal_close') 

ar(), 

dar(), 

dar(), 

«(), 

tory'), 

), 

ription '), 

[),’ 

), 

n:), 

ib, 

eD> 

r_none'), 

r_daily(), 

r_weeklyO, 

Link  to  calendar 

server 

me  al_e  vent_s  et_recu 

r_monthly_mday  [), 

me  al_e  vent_s  et_recu 

r_monthly_wday'), 

mcal_event_set_recu 
me  al_fe  tc  h_c  urrent_ 
me  al_e  vent_add_attr 

mcal expunge() 

r_yearly(), 

;tream_eventO, 

bute  {), 

SWFAction 

SWFBitmap 

SWFButton 

SWFDisplayltem 

SWFFill 

SWFFont 

SWFGradient 

SWFMorph 

SWFMovie 

SWFShape 

SWFSprite 

SWFText 

SWFTextField 

1252 


Apendice  F.  PFIP  Resource  Types 


Resource  Type 
Name 

Created  By 

Used  By 

Destroyed  By 

Definition 

mnogosearch  agent 

mnogosearch  result 

msql  link 

msql_connect ') 

msqlQ, 

msql_close  3 

Link  to  mSQL 

msql_create_db '), 
msql_createdb'), 
msql_drop_db '), 
msql_drop_db '), 
msql_select_db(), 
msql_select_db') 

database 

msql  link  persistent 

msql_pconnect') 

msql'), 

msql_create_db '), 
msql_createdb '), 
msql_drop_db '), 
msql_drop_db '), 
msql_select_db'), 
msql_select_db') 

None 

Persistent  link  to 
mSQL 

msql  query 

msql_query') 

msql '), 

msql_free_result  3, 

mSQL  result 

msql_affected_rows ' 

tnsql_frcc_result3 

msql_data_seek  ), 
msql_dbnarne 
msql_fetch_array '), 

msql_fetch_fieldO, 

msql_fetch_object '), 
msql_fetch_row '), 
msql_fieldname'), 
msql_field_seek '), 
msql_fieldtableO, 
msql_fieldtype  [), 
msql_fieldflags '), 
msqlfieldlen 

msql_num_fieldsO, 
msql_num_rows '), 
msqlnumfields '), 
msql_numrows '), 
msql_result') 

mssql  link 

mssql_connect ') 

mssql_query '), 

mssql_close  3 

Link  to  Microsft 

mssql_select_db') 

SQL  Server 
database 

mssql  link  persistent 

mssql_pconnect  3 

mssql_query '), 
mssql_select_db') 

None 

Persistent  link  to 
Microsft  SQL 

Server 
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Resource  Type 
Name 


Created  By 


Used  By 


Destroyed  By 


Definition 


mssql  result 


mssql_queryO 


mysql  link 


mysql_connect') 


mssql_ 

mssql_ 

mssql_ 

mssql_ 

mssql_ 

mssql_ 

mssql_ 

mssql_ 

mssql_ 

mssql_ 

mssql_ 

mssql_ 

mysql_ 

mysql_ 

mysql_ 

mysql_ 

mysql_ 

mysql_ 

mysql_ 

mysql_ 

mysql_ 

mysql_ 

mysql_ 

mysql_ 

mysql_ 

mysql_ 

mysql_ 

mysql_ 

mysql_ 

mysql_ 

mysql_ 

mysql_ 


_data_seek '), 
fetch_array  Q, 

fetch_field' ), 

fetch_object  '1 
fetch_row '), 

_field_length() 

_field_name() 

.field_seekO, 
_field_type(), 
num_fields'), 
num_rows  [), 
result ') 


mssql_free_result  [)  [Microsft  SQL 
Server  result 


alfccted_row4 

change_user' 

create_db'), 

data_seekO, 

_db_name(), 

db_query'), 

dropdb'), 

errno '), 

error'), 

insertid'), 

list_dbs'), 

list_fields'), 

list_tables '), 

query '), 

result'), 

select_db'), 

tablename '), 

_get_host_inf 

_get_proto_in|l 

_get_server_i 


mysql_closeO 

K 


Link  to  MySQL 
database 


0, 

fo(), 

info() 
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Resource  Type 
Name 


Created  By 


Used  By 


Destroyed  By 


Definition 


mysql  link  persistent 


mysql_pconnectO 


mysql_ 

mysql_ 

mysql_ 

mysql_ 

mysql 

mysql_ 

mysql_ 

mysql_ 

mysql_ 

mysql_ 

mysql_ 

mysql_ 

mysql_ 

mysql_ 

mysql_ 

mysql_ 

mysql_ 

mysql, 

mysql, 

mysql. 


affected_mw) 

change_user' 

create_db'), 

data_seekO, 

_db_name(), 

db_query'), 

dropdb'), 

errno  [), 

error'), 

insertid), 

list_dbs '), 

list_fields'), 

list_tables '), 

query '), 

result'), 

select_db(), 

tablename '), 

_get_host_inf 

_get_proto_in|l 

_get_server_i 


None 

o. 


Persistent  link  to 
MySQL  database 


0, 

foO, 

info() 


mysql  result 


mysql_db_query'), 

mysql_data_seekO, 

mysqllistdbs '), 

mysql_db_name(), 

my  sq  II  i  stfi  elds '), 

mysql_fetch_array'). 

mysql_list_tablesO, 

mysqlfetchassocl 

mysql_query') 

mysql_fetch_field '), 

mysql_fetch_lengths 

mysql_fetch_objecta 

mysql_fetch_row'), 

mysql_fetch_row'), 

mysql_field_flags(), 

mysql_field_name '), 

my  sql_field_len  {), 

my  sql_field_seek '), 

mysql_field_table  {), 

mysql_field_type'), 

mysql_num_fields '), 

mysql_num_rows'), 

mysqlresult'j, 

mysql_tablename ') 

mysql_free_resultO  MySQL  result 


oci8  collection 
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Resource  Type 
Name 

Created  By 

Used  By 

Destroyed  By 

Definition 

oci8  connection 

ocilogon'), 

ocicommit'). 

ocilogoff') 

Link  to  Oracle 

ociplogon'), 

ocinlogon') 

ociserverversion'), 

ocinewcursor'), 
ociparse(),  ocierrorO 

database 

oci8  descriptor 

oci8  server 

oci8  session 

oci8  statement 

ocinewdescriptor ') 

ocirollhack  ), 

ocifreestatement() 

Oracle  Cursor 

ocinewdescriptor  f), 
ocirowcount'), 
ocidetinebyname  {), 

ocibindbyname'), 

ociexecute'), 

ocinumcolsQ, 

ociresult'), 

ocifetch'), 

ocifetchintoO, 

ocifetchstatement  [), 
ocicolumnisnull  '), 
ocicolumnnameO, 
ocicolumnsize '), 
ocicolumntype '), 
ocistatementtype'), 
ocierror') 
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Resource  Type 
Name 


Created  By 


Used  By 


Destroyed  By 


Definition 


odbc  link 


odbc_connect') 


odbc_autocommit(), 

odbc_commitO, 

odbc_error(), 
odbc_errormsg(), 
odbc_exec(), 
odbc_tables(), 
odbc_tableprivilege|si 
odbc_do'), 

odbc_prcpare '), 

odbc_columns(), 
odbc_columnprivili 
ndhcproced  u  recoil^  inns!) 
odbc_specialcolumi 
odbc_rollback(), 
odbc_setoption  {), 
odbc_gettypeinfo(), 
odbc_primarykeys(t) 
odbc_foreignkeys(), 
odbc_procedures(), 
odbc statistics() 


odbc_close') 


Link  to  ODBC 
database 


>0, 


eges(). 


rs(). 


odbc  link  persistent 


odbc_connect') 


odbc_autocommitO,  None 
odbc_commitO, 

odbc_error(), 
odbc_errormsg(), 
odbc_exec'), 
odbc_tables(), 
odbc_tableprivilege|si 
odbc_do' ), 
odbc_prepare(), 
odbc_columns(), 
odbc_columnprivile|: 
odbc_procedurecoli  i: 
odbc_specialcolumi 
odbc_rollback(), 
odbc_setoption  [), 
odbc_gettypeinfo(), 
odbc_primarykeys(|) 
odbc_foreignkeys(), 
odbc_procedures(), 
odbc_statistics() 


Persistent  link  to 
ODBC  database 


!(), 


ges(), 

mns(), 

4s(). 
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Resource  Type 
Name 

Created  By 

Used  By 

Destroyed  By 

Definition 

odbc  result 

odbc_prepareO 

odbc_binmode'), 

odbc_free_result  3 

ODBC  result 

odbc_cursor'), 

odbc_execute'), 

odbc_fetch_into '), 

odbc_fetch_row  3, 

odbc_field_nameO, 

odbc_field_num(), 

odbc_field_type'), 

odbc_field_len  [), 

odbc_field_precisioi 

odbc_field_scale(), 

odbcjongreadlcn), 

odbc_num_fields'), 

odbc_num_rows  3, 

odbc_result3, 

odbc_result_all'3, 

odbc_setoption3 

i(). 

velocis  link 

velocis  result 

OpenSSL  key 

openssl_sign), 

opens  sl_free_key  3 

OpenSSL  key 

opens  sl_get_privatel< 

sp9nssl_seal  3, 

opens  sl_get_publick 

(jjji^nssl_open'3, 

openssl_verify  3 

OpenSSL  X.509 

Public  Key 

opens  sl_x509_read() 

openssl_x509_parse ; 

!ftpenssl_x509_free  3 

openssl_x509_check 

turposeO 

oracle  Cursor 

ora_openO 

ora_bind'3, 

ora_close  3 

Oracle  cursor 

ora_columnname'3, 
ora_columnsize(), 
ora_columntype  3, 
ora_errorO, 
ora  errorcode3, 
ora_exec  3, 
ora_fetch  3, 
ora_fetch_into(), 

ora_getcolumn'3. 

ora_numcols(), 

ora_numrows(), 

ora_parse) 
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Resource  Type 
Name 

Created  By 

Used  By 

Destroyed  By 

Definition 

oracle  link 

ora_logonO 

ora_do(), 

ora_error'), 
ora_errorcode '), 
ora_rollback '), 

ora_commitoff'), 
ora_commitonO, 
ora_open'), 
ora commit ') 

ora_logot’f ') 

Link  to  oracle 

database 

oracle  link  persistent 

ora_plogon() 

ora_do(), 

ora_error'), 
ora_errorcode '), 
ora_rollbacl< '), 
ora_commitoff ') , 
ora  commiton'), 
ora_open  J, 
ora_commit  [) 

None 

Persistent  link  to 

oracle  database 

1259 


Apendice  F.  PFIP  Resource  Types 


Resource  Type 
Name 

Created  By 

Used  By 

Destroyed  By 

Definition 

pdf  document 

pdf_new() 

pdf_add_bookmark 

pdf_add_launchlinl 

pdf_add_locallink() 

pdf_add_note(), 

pdf_add_pdflink(), 

pdf_add_weblink(), 

pdf_arc  t), 

pdf_attach_file(), 

pdf_begin_page '), 

pdf_circle'), 

pdf_clip'), 

pdf_closepath  3, 

pdf_closepath_fill_st 

pdf_closepath_strokt 

pdf_concat(), 

pdf_continue_text(), 

pdf_curvetoO, 

pdfendpage), 

pdf_endpath '), 

pdf_fi  1 1 ;), 

pdf_fill_stroke'), 

pdf_findfont(), 

pdf_get_buffer(), 

pdf_get_image_heij 

pdf_get_image_wid 

pdf_get_parameter  h, 

pdf_get_value(), 

pdf_lineto '), 

pdf_moveto(), 

pdf_open_ccitt(), 

pdf_open_file(), 

pdf_open_image_fil 

pdf_place_image '), 

pdf_rect'), 

pdf_restoreQ, 

pdf_rotate '), 

pdf_save(), 

pdf_scale'), 

pdf_setdash(), 

pdf_setflat'), 

pdf_setfont(), 

pdf_setgray(), 
pdf_setgray_fill '), 
pdf_setgray_stroke ') 
pdfsetlinecap), 
pdtsetlinejoin '), 
pdfsetlinewidth '), 
pdf_setmiterlimitO, 
pdf_setpolydash() , 
pdf_setrgbcolorO, 
pdf_setrgbcolor_fill' 
pdf_setrgbcolor_stro 

pdf_closeO, 

$Jf_delete() 

roke '), 

p, 

ht(), 

th(), 

e(), 

*3. 

PDF  document 
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Resource  Type 
Name 

Created  By 

Used  By 

Destroyed  By 

Definition 

pdf  image 

pdf_open_image(), 

pdf_open_image_lil 

pdf_open_memory_i 

p(df_get_image_hei| 
pdtq  letimagevvid 
pdf_open_CCITT() 

pdf_place_image ') 

pdf_close_imageO 

ht(), 

th(). 

Image  in  PDF  file 

pdf  object 

pdf  outline 

pgsql  large  object 

pg_getlastoid'), 

pg_loopen '), 

pg_loclose  [) 

PostGreSQL  Large 

pg_loimport(), 

pg_loimport() 

pg_getlastoid '), 
pg_locreate '), 
pg_loexport(), 
pg_loreadj), 
pg_loreadall  J, 
pg_lounlink'), 
pg_lo  write ') 

Object 

pgsql  link 

pg_connect') 

pg_cmdtuples(). 

pg_close() 

Link  to  PostGreSQL 

pg_dbname ;), 

pg_end_copy(), 
pg_errormessage  {), 
pg_host(), 
pg_locreate  [), 

pg_loexport(), 

pg_loimport(), 

pg_loopen), 

pg_lounlinki), 

pg_options  [), 

pg_port ), 

pg_put_line(), 

pgsetclientencoc 

pgcl  ientencod  i  ng 

pg_trace(), 

pg_untrace(), 

pg-ttyO 

ing(), 

X 

database 
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Resource  Type 
Name 

Created  By 

Used  By 

Destroyed  By 

Definition 

pgsql  link  persistent 

pg_pconncct') 

pg_cmdtuples'), 

pg_dbname '), 
pg_end_copy(), 
pg_errormessage '), 
pg_hostO, 
pg_locreate '), 
pg_loexport(), 
pg_loimport(), 
pgJoopenO, 

pg_lounlinl< ' ), 
pg_options  [), 

pg_portO, 

pg_put_line(), 

pgsetclientencot 

pg_client_encodingi 

pg_trace(), 

pg_untrace(), 

pg-ttyO 

None 

ing(), 

). 

Persistent  link  to 

PostGreSQL 

database 

pgsql  result 

pg_execO 

pg_fetch_array '), 

pg_freeresult  [) 

PostGreSQL  result 

pg_fetch_object'), 

pg_fieldisnull(), 
pg_fetch_row3, 
pg_fieldnameO, 
pg_fieldnum '), 

pg_fieldprtlen'), 
pg_fieldsize  [), 
pg_fieldtype '), 
pg_getlastoid '), 
pg_numfields'), 
pg_result'), 
pg_numrows ') 

pgsql  string 

printer 

printer  brush 

printer  font 

printer  pen 
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Resource  Type 
Name 

Created  By 

Used  By 

Destroyed  By 

Definition 

pspell 

pspell_newO, 

pspell_new_config() 

pspellnewpersom 

pspell_add_to_pers 

|kfc)pell_add_to_sessi 

pspellcheck'), 

pspell_clear_sessior 

pspell_conlig_ignor 

pspell_config_mode 

pspell_conlig_perso 

pspell_conflg_repl() 

pspell_config_runto 

pspell_conflg_save_ 

pspell_save_wordlis 

pspellstorereplac 

pspell_suggest') 

None 

mal(), 

>n(), 

0, 

:(), 

0, 

ial(), 

gether(), 

repl(), 

t(), 

!ment(), 

pspell  dictionary 

pspell  config 

pspell_config_creat* 

|$$pellnevvconfigO 

None 

pspell  configuration 

Sablotron  XSLT 

xslt_create ') 

xslt_closelog3. 

xslt_free') 

XSLT  parser 

xslt_openlog(), 

xslt_run'), 

xslt_set_sax_handler 
xslt_errno'), 
xslt_error'), 
xslt_fetch_result  3, 
xslt free) 

3, 

shmop 

shmop_open() 

shmop_read(), 
shmop_write(), 
shmop_size(), 
shmop delete() 

shmop_close() 

sockets  file 
descriptor  set 

socket  3 

accept_connectO, 
bind  3,  connect;), 
listen;),  read(), 
writef) 

closef) 

Socket 

sockets  i/o  vector 

dir 

dir() 

readdii\), 

rewinddir)) 

closedirO 

Dir  handle 
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Resource  Type 
Name 

Created  By 

Used  By 

Destroyed  By 

Definition 

file 

fopcn ') 

feof)),  fflushf), 
fgetc)),  fgetcsvf), 
fgets)),  fgetss)), 
flock'),  fpassthru)), 
fputs)),  fwrite)), 
fread)),  fseek '), 

ftell ;),  fstat(), 
ftruncatef), 
set_file_buffer)), 
rewind') 

fclose  [) 

File  handle 

pipe 

popen) 

feof  ),  fflushf), 
fgetc)),  fgetcsv)), 
fgets'),  fgetssi'), 
fpassthru  '),  fputs  3, 
fwriteO,  fread ') 

pclose ') 

Process  handle 

socket 

fsockopen') 

fflushf),  fgetc)), 
fgetcsv)),  fgets)), 
fgetss3,  fpassthru)), 
fputs)),  fwrite)), 
fread)) 

fclose ') 

Socket  handle 

stream 

sybase-db  link 

sybase_connect)) 

sybase_query)). 

sybase_close)) 

Link  to  Sybase 

sybase_select_db)) 

database  using  DB 
library 

sybase-db  link 

sybase_pconnect)) 

sybase_query)), 

None 

Persistent  link  to 

persistent 

sybase_select_db)) 

Sybase  database 
using  DB  library 

sybase-db  result 

sybase_queryO 

sybase_data_seek'), 

sybase_free_result )) 

Sybase  result  using 

sybase_fetch_array)) 
sybase_fetch_field'), 
sybase_fetch_object ' 
sybase_fetch_row )), 
sybase_field_seek  3, 
sybase_num_fields)) 
sybase_num_rows )), 
sybase_result)) 

), 

DB  library 

sybase-ct  link 

sybase_connect'j 

sybase_close)) 

Link  to  Sybase 

sybase_affected_row 

sybase_query)), 

sybase_select_db)) 

sO, 

database  using  CT 
library 
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Resource  Type 
Name 

Created  By 

Used  By 

Destroyed  By 

Definition 

sybase-ct  link 

sybase_pconnect') 

None 

Persistent  link  to 

persistent 

sybase_affected_row 

sybase_queryO, 

sybase_select_db'3 

o, 

Sybase  database 
using  CT  library 

sybase-ct  result 

sybase_queryO 

sybase_data_seek'), 

sybase_free_result  [) 

Sybase  result  using 

sybase_fetch_arrayO 
sybase_fetch_fiekL), 
sybase_fetch_object ' 
sybase_fetch_row  [), 
sybase_field_seek '), 
sybase_num_fieldsO 
sybase_num_rows '), 
sybase_result3 

), 

CT  library 

sysvsem 

sem_get') 

sem_acquireO 

sem_release ') 

System  V 

Semaphore 

sysvshm 

shm_attachO 

shm_remove '), 

shm_detach' ) 

System  V  Shared 

shm_put_var '), 
shm_get_var'), 
shm remove var') 

Memory 

wddx 

wddx_add_vars ') 

wddx_packet_end ') 

WDDX  packet 

wddx_packet_start  {) 

xml 

xml_parser_create ') 

xml_set_objectO, 

xml_parser_free  {) 

XML  parser 

xml_set_element_ha 

xml_set_character_d 

idler  3. 
ita_handlei\). 

xml_set_processing_|instruction_handlerC 

, 

xml_set_default_han|dler'), 

xml_set_unparsed_ei 

itity_decl_handler 

xml_set_notation_de|el_handler(). 

xml_set_external_en 

ity_ref_handlcr). 

xml_parse), 

xml_get_error_code ' 

xml_error_stringO, 

xml_get_current_lin( 

xml_get_current_col 

xml_get_current_byt 

xml_parse_into_str 

xml_parser_set_opti( 

x  m  1  _p  a  rs  e  r_ge  t_o  p  t  i 

), 

_number'j, 
imn_n  umber'), 
;_indcx '), 
ict(), 

»np, 

>n ') 
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Resource  Type 
Name 

Created  By 

Used  By 

Destroyed  By 

Definition 

zlib 

gzopen() 

gzeofO,  gzgetcO, 
gzgets'),  gzgetss'), 
gzpassthru'), 
gzputs(),  gzread'), 
gzrewind'), 
gzseek'),  gztell^), 
gzwriteO 

gzclose') 

gz-compressed  file 

1266 


Apendice  G.  Aliases  list 


1267 


Apendice  G.  Aliases  list 


Here  is  the  aliases  list.  All  aliases  are  listed  here.  It  is  usually  a  bad  idea  to  use  aliases,  are  they  may  be 
bound  to  obsolescence  or  renaming,  which  will  lead  to  unportable  script.  This  list  is  provided  to  help 
those  who  want  to  upgrade  their  old  scripts  to  newer  syntax. 

However,  some  functions  simply  have  two  names,  and  there  is  no  real  preference.  (For  example,  is_i  nt) 
and  is_integer)  are  equally  good) 

This  list  is  consistent  with  PHP  4.0.6. 


Tabla  G-l.  Aliases 


Alias 

Master  function 

Extension  used 

add 

swfmovie add() 

Ming  (flash) 

add 

swfsprite add() 

Ming  (flash) 

add root 

domxml add root() 

DOM  XML 

addaction 

swfbutton addAction() 

Ming  (flash) 

addcolor 

swfdisp!ayitem addColor( ) 

Ming  (flash) 

addentry 

swfgradient addEntry() 

Ming  (flash) 

addfill 

swfshape addfill() 

Ming  (flash) 

addshape 

swfbutton addShape() 

Ming  (flash) 

addstring 

swftext addString() 

Ming  (flash) 

addstring 

swftextfield addString() 

Ming  (flash) 

align 

swftextlield align() 

Ming  (flash) 

attributes 

domxml attributes() 

DOM  XML 

children 

domxml children() 

DOM  XML 

chop 

rtrirn') 

Base  syntax 

close 

_ 

closedirj) 

Base  syntax 

com get 

com_propget') 

COM 

com propset 

com_propput() 

COM 

com set 

com_propput() 

COM 

cv add 

ccvs add() 

CCVS 

cv auth 

ccvs auth() 

CCVS 

cv command 

ccvs command() 

CCVS 

cv count 

ccvs count() 

CCVS 

cv delete 

ccvs delete() 

CCVS 

cv done 

ccvs done() 

CCVS 

cv init 

ccvs init() 

CCVS 

cv lookup 

ccvs lookup() 

CCVS 

cv new 

ccvs new() 

CCVS 

cv report 

ccvs report() 

CCVS 

cv return 

ccvs retum() 

CCVS 

cv_reverse 

ccvs_reverse() 

CCVS 
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Alias 

Master  function 

Extension  used 

cv sale 

ccvs sale() 

ccvs 

cv status 

ccvs status() 

ccvs 

cv textvalue 

ccvs textvalue() 

ccvs 

cv void 

ccvs void() 

ccvs 

die 

exit ') 

Miscellaneous  functions 

dir 

getdirO 

Base  syntax 

domxml getattr 

domxmI get attribute() 

DOM  XML 

domxml setattr 

domxml set attribute() 

DOM  XML 

doubleval 

floatval() 

Base  syntax 

drawarc 

swfshape drawarc() 

Ming  (flash) 

drawcircle 

swfshape drawcircle() 

Ming  (flash) 

drawcubic 

swfshape drawcubic() 

Ming  (flash) 

drawcubicto 

swfshape drawcubicto() 

Ming  (flash) 

drawcurve 

swfshape drawcurve() 

Ming  (flash) 

drawcurveto 

swfshape drawcurveto() 

Ming  (flash) 

drawglyph 

swfshape drawglyph() 

Ming  (flash) 

drawline 

swfshape drawline() 

Ming  (flash) 

drawlineto 

swfshape drawlineto() 

Ming  (flash) 

dtd 

domxmt intdtd  ( ) 

DOM  XML 

dumpmem 

dom  xm  Id  n  in  pmem  ( ) 

DOM  XML 

fbsql 

Fbsql_db_query ') 

FrontBase 

fputs 

“write') 

Base  syntax 

get attribute 

domxml get attribute() 

DOM  XML 

getascent 

swffont getAscent() 

Ming  (flash) 

getascent 

swftext getAscent() 

Ming  (flash) 

getattr 

domxmt get attribute() 

DOM  XML 

getdescent 

swffont getDescent() 

Ming  (flash) 

getdescent 

swftext getDescent() 

Ming  (flash) 

getheight 

swfbitmap getHeight() 

Ming  (flash) 

getleading 

swffont getLeading() 

Ming  (flash) 

getleading 

swftext getLeading() 

Ming  (flash) 

getshapel 

swfmorph getShape  1  () 

Ming  (flash) 

getshape2 

swfmorph getShape2() 

Ming  (flash) 

getwidth 

swfbitmap getWidth() 

Ming  (flash) 

getwidth 

swffont getWidth() 

Ming  (flash) 

getwidth 

swftext getWidth() 

Ming  (flash) 

gzputs 

gzwrite ') 

Zlib 

i  1 8n convert 

mb_convert_enc  oding') 

Multi-bytes  Strings 
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Alias 

Master  function 

Extension  used 

i  1 8n discover encoding 

mb_detect_cncoding ') 

Multi-bytes  Strings 

i  1 8n http input 

mb_http_input  |) 

Multi-bytes  Strings 

i  1 8n http output 

mb_http_output() 

Multi-bytes  Strings 

i  1 8n internal encoding 

mb_internal_encoding ') 

Multi-bytes  Strings 

i  1 8n j  a jp hantozen 

mb convert kana() 

Multi-bytes  Strings 

i  1 8n mime header decode 

mb decode mimeheader') 

Multi-bytes  Strings 

i  1 8n mime header encode 

mb encode mimeheadei\) 

Multi-bytes  Strings 

imap create 

imap_createmailbox') 

IMAP 

imap fetchtext 

imap_body() 

IMAP 

imap getmailboxes 

imap list full() 

IMAP 

imap getsubscribed 

imap lsub full() 

IMAP 

imap header 

imap headerinfo() 

IMAP 

imap listmailbox 

imap list() 

IMAP 

imap listsubscribcd 

imap lsub() 

IMAP 

imap rename 

imap_renamemailboxO 

IMAP 

imap scan 

imap listscan() 

IMAP 

imap sc  anmailbox 

imap listscan() 

IMAP 

ini alter 

ini set() 

Base  syntax 

is double 

is float() 

Base  syntax 

is integer 

is int{) 

Base  syntax 

is long 

is int ') 

Base  syntax 

is real 

is float() 

Base  syntax 

is writeable 

is writable() 

Base  syntax 

join 

implode) 

Base  syntax 

labelframe 

swfmovieJabelF  rame() 

Ming  ( flash) 

labelframe 

swfsprite labelF  rame() 

Ming  (flash) 

last child 

domxml last child() 

DOM  XML 

lastchild 

domxml last child() 

DOM  XML 

ldap close 

ldap_unbind ') 

LDAP 

magic quotes runtime 

set_magic_quotes_runtime() 

Base  syntax 

mbstrcut 

mb strcut() 

Multi-bytes  Strings 

mbstrlen 

mb strlen ') 

Multi-bytes  Strings 

mbstrpos 

mb_strpos() 

Multi-bytes  Strings 

mbstrrpos 

mb_strrpos() 

Multi-bytes  Strings 

mbsubstr 

mb substr') 

Multi-bytes  Strings 

ming setcubicthreshold 

ming setCubicThreshold( ) 

Ming  (flash) 

ming setscale 

ming setScale() 

Ming  (flash) 

move 

swfdisplayitem move() 

Ming  (flash) 
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Alias 

Master  function 

Extension  used 

movepen 

swfshape movepen() 

Ming  (flash) 

movepento 

swfshape movepento() 

Ming  (flash) 

moveto 

swfdisplayitem moveTo() 

Ming  (flash) 

moveto 

swffiIl moveTo() 

Ming  (flash) 

moveto 

swftext moveTo() 

Ming  (flash) 

msql 

msql db query() 

mSQL 

msql affected rows 

msql_affected_rows ') 

mSQL 

msql createdb 

msql_create_db') 

mSQL 

msql dbname 

msql_result ') 

mSQL 

msql dropdb 

msqldropdb ') 

mSQL 

msql fieldflags 

msql field flags() 

mSQL 

msql fieldlen 

msql field len() 

mSQL 

msql fieldname 

msql field name() 

mSQL 

msql fieldtable 

msql field table() 

mSQL 

msql fieldtype 

msql field type() 

mSQL 

msql freeresult 

msql_free_result') 

mSQL 

msql listdbs 

msql_list_dbs  3 

mSQL 

msql listfields 

msql_list_fields') 

mSQL 

msql listtables 

msql_list_tables') 

mSQL 

msql numfields 

msqlnumfields ') 

mSQL 

msql numrows 

msql_num_rows ') 

mSQL 

msql regcase 

sql_regcase() 

mSQL 

msql selectdb 

msql_select_db') 

mSQL 

msql tablename 

msql_result  3 

mSQL 

mssql affected rows 

sybase_affected_rows  3 

Sybase 

mssql affected rows 

sybase_affected_rows  3 

Sybase 

mssql close 

sybase_close ') 

Sybase 

mssql close 

sybase_close ') 

Sybase 

mssql connect 

sybase_connect') 

Sybase 

mssql connect 

sybase_connect') 

Sybase 

mssql data seek 

sybase_data_seek() 

Sybase 

mssql data seek 

sybase_data_seek') 

Sybase 

mssql fetch array 

sybase_fetch_array  [) 

Sybase 

mssql fetch array 

sybase_fetch_array  [) 

Sybase 

mssql fetch field 

sybase_fetch_field') 

Sybase 

mssql fetch field 

sybase_fetch_ficld  ) 

Sybase 

mssql fetch object 

sybase_fetch_object ') 

Sybase 

mssql fetch object 

sybase_fetch_object ') 

Sybase 
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Alias 

Master  function 

Extension  used 

mssql fetch row 

sybase_fetch_row ') 

Sybase 

mssql fetch row 

sybase_fetch_row ') 

Sybase 

mssql field seek 

sybase_field_seek ') 

Sybase 

mssql field seek 

sybase_field_seek ') 

Sybase 

mssql free result 

sybase_free_result() 

Sybase 

mssql free result 

sybase_free_result() 

Sybase 

mssql get last message 

sybase get last message() 

Sybase 

mssql get last message 

sybase get last message() 

Sybase 

tnssql min client severity 

sybase min client severity() 

Sybase 

mssql min error severity 

sybase min error severity() 

Sybase 

mssql min message severity 

sybase min message severity() 

Sybase 

mssql min server severity 

sybase min server severity() 

Sybase 

mssql num fields 

sybase_num_ficlds ') 

Sybase 

mssql num fields 

sybase_num_fields') 

Sybase 

mssql num rows 

sybase_num_rows ') 

Sybase 

mssql num rows 

sybase_num_rows ') 

Sybase 

mssql pconnect 

sybase_pconnectO 

Sybase 

mssql pconnect 

sybase_pcon  ncct') 

Sybase 

mssql query 

sybase_query)) 

Sybase 

mssql query 

sybase_query() 

Sybase 

mssql result 

sybase_result  3 

Sybase 

mssql result 

sybase_result  3 

Sybase 

mssql select db 

sybase_select_dbO 

Sybase 

mssql select db 

sybase_select_db() 

Sybase 

multcolor 

swfdisplayitem multColor() 

Ming  (flash) 

mysql 

mysql_db_queryO 

[MySQL 

mysql createdb 

mysql_create_db  3 

[MySQL 

mysql db name 

mysqlresult)) 

[MySQL 

mysql dbname 

mysql_result3 

[MySQL 

mysql dropdb 

mysql_drop_db  3 

[MySQL 

mysql fieldflags 

mysql_field_flags'3 

[MySQL 

mysql fieldlen 

my  sql_field_len  3 

[MySQL 

mysql fieldname 

mysql_field_name ') 

[MySQL 

mysql fieldtable 

mysql_field_table  3 

[MySQL 

mysql fieldtype 

mysql_field_typeO 

[MySQL 

mysql freeresult 

mysql_free_result  3 

[MySQL 

mysql listdbs 

mysql_list_dbs  3 

[MySQL 

mysql listfields 

mysql_list_fields  3 

[MySQL 
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Alias 

Master  function 

Extension  used 

mysql listtables 

my  sql_list_tables ') 

MySQL 

mysql numfields 

mysql_num_fields ') 

MySQL 

mysql numrows 

_ 

mysql_num_rows  Q 

MySQL 

mysql selectdb 

mysql_select_db') 

MySQL 

mysql tablename 

mysqlresult'j 

MySQL 

name 

domxml attrname() 

DOM  XML 

new child 

domxmt new child() 

DOM  XML 

new xmldoc 

domxml new xmldoc() 

DOM  XML 

nextframe 

swfmovie nextF  rame() 

Ming  (flash) 

nextframe 

swfsprite nextF  rame() 

Ming  (flash) 

node 

domxml node() 

DOM  XML 

oci8append 

ocicollappendO 

OCI8 

oci8assign 

ocicollassign() 

OCI8 

oci8assignelem 

ocicollassignelemO 

OCI8 

oci8close 

ocicloselob() 

OCI8 

oci8free 

ocifreecollO 

OCI8 

oci8free 

ocifreedescO 

OCI8 

oci8getelem 

ocicollgetelemO 

OCI8 

oci81oad 

ociloadlob() 

OCI8 

oci8max 

ocicollmax() 

OCI8 

oci8ocifreecursor 

ocifreestatement ) 

OCI8 

oci8save 

ocisavelobO 

OCI8 

oci8savefile 

ocisavelobfileO 

OCI8 

oci8size 

ocicollsizeO 

OCI8 

oci8trim 

ocicolltrim() 

OCI8 

oci  8  writetemporary 

ociwritetemporarylob() 

OCI8 

oci8writetofile 

ociwritelobtofileO 

OCI8 

odbc do 

odbc exec') 

OCI8 

— 

odbc field precision 

— 

odbc field len  ') 

OCI8 

orbit caught exception 

satellite caught exception() 

Satellite 

orbit exception id 

satellite exception id() 

Satellite 

orbit exception value 

satellite exception value() 

Satellite 

orbit get repository id 

satellite get repository id() 

Satellite 

orbit load idl 

satellite load idl() 

Satellite 

output 

swfmovie output() 

Ming  (flash) 

parent 

domxmI parent() 

DOM  XML 

pdf add outline 

pdf add bookmark() 

PDF 

pg clientencoding 

pg client encoding() 

PostgreSQL 
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Alias 

Master  function 

Extension  used 

pg setclientencoding 

Pg set client encoding() 

PostgreSQL 

pos 

current  f) 

Base  syntax 

recode 

recode_string() 

Recode 

remove 

swfmovie remove() 

Ming  (flash) 

remove 

swfsprite remove() 

Ming  (flash) 

rewind 

rewinddir') 

Base  syntax 

root 

domxml root() 

DOM  XML 

rotate 

swfdisplayitem rotate() 

Ming  (flash) 

rotateto 

swfdisplayitem rotateTo() 

Ming  (flash) 

rotateto 

swffill rotateTo() 

Ming  (flash) 

save 

swfmovie save() 

Ming  (flash) 

savetofile 

swfmovie saveToFile() 

Ming  (flash) 

scale 

swfdisplayitem scale() 

Ming  (flash) 

scaleto 

swfdisplayitem scaleTo() 

Ming  (flash) 

scaleto 

swffill scaleTo() 

Ming  (flash) 

set attribute 

domxml set attribute() 

DOM  XML 

set content 

domxml set content() 

DOM  XML 

setaction 

swfbutton setAction() 

Ming  (flash) 

setattr 

domxml set attribute() 

DOM  XML 

setbackground 

swfmovie setBackground() 

Ming  (flash) 

setbounds 

swftextfield setBounds() 

Ming  (flash) 

setcolor 

swftext setColor() 

Ming  (flash) 

setcolor 

swftextfield setColor() 

Ming  (flash) 

setdepth 

swfdisplayitem setDepth() 

Ming  (flash) 

setdimension 

swfmovie setDimension() 

Ming  ( flash) 

setdown 

swfbutton setDown() 

Ming  (flash) 

setfont 

swftext setFont() 

Ming  (flash) 

setfont 

swftextfield setF  ont() 

Ming  (flash) 

setframes 

swfmovie setFrames() 

Ming  (flash) 

setframes 

swfsprite setF  rames() 

Ming  (flash) 

setheight 

swftext setFIeight() 

Ming  (flash) 

setheight 

swftextfield setFIeight() 

Ming  (flash) 

sethit 

swfbutton setFIit() 

Ming  (flash) 

setindentation 

swftextfield setIndentation() 

Ming  (flash) 

setleftfill 

swfshape setleftfill() 

Ming  (flash) 

setleftmargin 

swftextfield setLeftMargin() 

Ming  (flash) 

setline 

swfshape setline() 

Ming  (flash) 

setlinespacing 

swftextfield setLineSpacing() 

Ming  (flash) 

1274 


Apendice  G.  Aliases  list 


Alias 

Master  function 

Extension  used 

setmargins 

swftextfield setMargins() 

Ming  ( flash) 

setmatrix 

swfdisplayitem setMatrix() 

Ming  (flash) 

setname 

swfdisplayitem setName() 

Ming  (flash) 

setname 

swftextfield setName() 

Ming  (flash) 

setover 

swfbutton setOver() 

Ming  (flash) 

setrate 

swfmovie setRate() 

Ming  (flash) 

setratio 

swfdisplayitem setRatio() 

Ming  (flash) 

setrightfill 

swfshape setrightfill() 

Ming  (flash) 

setrightmargin 

swftextfield setRightMargin() 

Ming  (flash) 

setspacing 

swftext setSpacing() 

Ming  (flash) 

setup 

swfbutton setUp() 

Ming  (flash) 

show source 

highlight file  () 

Base  syntax 

sizeof 

count') 

Base  syntax 

skewx 

swfdisplayitem skewX() 

Ming  (flash) 

skewxto 

swfdisplayitem skewXTo() 

Ming  (flash) 

skewxto 

swffill skewXTo() 

Ming  (flash) 

skewy 

swfdisplayitem skew  Y  () 

Ming  (flash) 

skewyto 

swfdisplayitem skewYTo() 

Ming  (flash) 

skewyto 

swffitl skewYTo() 

Ming  (flash) 

snmpwalkoid 

snmprealwalk() 

SNMP 

strchr 

strstr') 

Base  syntax 

streammp3 

swfmovie streamMp3() 

Ming  (flash) 

swfaction 

swfaction init() 

Ming  (flash) 

swfbitmap 

swfbitmap init() 

Ming  (flash) 

swfbutton 

swfbutton init() 

Ming  ( flash) 

swfbutton keypress 

swfbutton keypress() 

Ming  (flash) 

swffill 

swffill init() 

Ming  (flash) 

swffont 

swffont init() 

Ming  (flash) 

swfgradient 

swfgradient init() 

Ming  (flash) 

swfmorph 

swfmorph init() 

Ming  (flash) 

swfmovie 

swfmovie init() 

Ming  (flash) 

swfshape 

swfshape init() 

Ming  (flash) 

swfsprite 

swfsprite init() 

Ming  (flash) 

swftext 

swftext init() 

Ming  (flash) 

swftextfield 

swftextfield init() 

Ming  (flash) 

unlink 

domxmt unlink node() 

DOM  XML 

xpath eval 

xpath eval() 

DOM  XML 

xp  ath_e  val_expre  s  sion 

xpath_eval_expression() 

DOM  XML 
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Alias 

Master  function 

Extension  used 

xpath init 

xpath init() 

DOM  XML 

xp  ath new c  ontext 

xpath new context() 

DOM  XML 

xptr_new_context 

xpath_new_context() 

DOM  XML 
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The  command  line  options  of  the  PHP  executable  are  useful  if  you  would  like  to  debug  or  test  your  PHP 
setup,  but  they  can  also  be  handy,  if  you  would  like  to  use  PHP  for  a  different  purpose  than  web  scripting. 

Note,  that  you  can  always  direct  the  output  of  the  PHP  executable  to  an  external  file  with  the  >  character, 
so  php  — q  test .  php  >  test .  html  will  print  out  the  output  of  test .  php  without  HTTP  headers  to 
the  test .  html  file  in  the  same  directory. 

You  can  only  use  these  command  line  options  if  you  have  the  PHP  executable.  If  you  built  the  server 
module  version,  and  you  have  no  CGI  version  available  on  your  machine,  than  you  have  no  chance  to  use 
these  options.  For  Windows  users  both  the  PHP  executable  and  the  server  modules  are  in  the  binary 
package,  the  executable  is  named  php .  exe. 

This  list  of  command  line  options  is  consistent  with  PHP  4.0.6.  You  can  get  the  actual  list  and  some  one 
line  descriptions  with  the  -h  option.  The  output  of  php  -h  should  be  something  like  this: 


Usage:  php  [ — q ] 

-q 

-s 

-f  <file> 

-v 

-C 

-c  <path> 

-d  foo[=bar] 
-e 

-z  <file> 

-m 

-i 

-h 


[  — h ]  [  —  s  [-v]  [ — ± ]  [-f  <file>]  I  {<file>  [args. . .] ) 
Quiet-mode.  Suppress  HTTP  Header  output. 

Display  colour  syntax  highlighted  source. 

Parse  <file>.  Implies  '-q' 

Version  number 

Do  not  chdir  to  the  script's  directory 
Look  for  php. ini  file  in  this  directory 
Define  INI  entry  foo  with  value  'bar' 

Generate  extended  information  for  debugger/profiler 
Load  Zend  extension  <file>. 

Syntax  check  only  (lint) 

Show  compiled  in  modules 
PHP  information 
This  help 


Here  we  list  some  of  the  most  important  command  line  options  with  detailed  explanations. 


Tabla  H-l.  Command  line  options 


Option 

Description 

-q 

Suppress  HTTP  headers  output.  Normally  PHP 
prints  out  HTTP  headers  for  the  calling  program  (ie. 
Webserver)  to  hand  on  to  the  browser.  When  writing 
command  line  applications  these  headers  are 
useless. 

-S 

Display  the  color  highlighted  source  of  the  file 
given  with  its  name.  This  is  the  same  as  if  you  were 
printing  out  the  source  using  the  highlight_file() 
function  in  a  PHP  script. 

-V 

By  calling  PHP  with  this  option,  you  can  ask  it  to 
print  out  its  version  number,  ie:  4.0.6. 
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Option 

Description 

-C 

Normally  PHP  changes  the  working  directory  to  the 
running  scripts  direcrory.  This  makes  it  possible  for 
example,  to  open  hies  in  the  same  directory,  with 
only  specifying  the  name  of  the  hie.  If  you  would 
like  to  disable  this  directory  change,  use  this  option. 

-C 

Using  this  option,  you  can  specify  an  alternative 
php .  ini  path,  so  PHP  will  search  your 
conhgurations  hie  in  this  path  instead  of  the  default 

one. 

-d 

With  this  option,  you  can  set  individual  php .  ini 
settings  in  the  time  of  running  a  script. 

-m 

Using  this  option,  PHP  prints  out  the  built  in  (and 
loaded)  PHP  and  Zend  modules,  the  PHP  and  Zend 
version  numbers,  and  a  short  Zend  copyright  notice. 

-i 

This  command  line  option  calls  phpinfo  ),  and 
prints  out  the  results.  If  PHP  is  not  working  well,  it 
is  advisable  to  make  a  php  -i  and  see  if  any  error 
messages  are  printed  out  before  or  in  place  of  the 
information  tables. 

-h 

With  this  option,  you  can  get  information  about  the 
actual  list  of  command  line  options  and  some  one 
line  descriptions  about  what  they  do. 

The  PHP  executable  can  be  used  to  run  PHP  scripts  absolutely  independent  from  the  web  server.  If  you 
are  on  a  Unix  system,  you  should  add  a  special  hrst  line  to  your  PHP  script,  and  make  it  executable,  so 
the  system  will  know,  what  program  should  run  the  script.  On  a  Windows  platform  you  can  associate 
php .  exe  -q  with  the  double  click  option  of  the  .  php  files,  or  you  can  make  a  batch  hie  to  run  the  script 
through  PHP.  The  hrst  line  added  to  the  script  to  work  on  Unix  won’t  hurt  on  Windows,  so  you  can  write 
cross  platform  programs  this  way.  A  simple  example  of  writing  a  command  line  PHP  program  can  be 
found  below. 

Ejemplo  H-l.  Script  intended  to  be  run  from  command  line  (script.php) 

# ! /usr /bin/php  -q 
<?php 

if  ( $argc  !=  2  ||  in_array ( $argv [ 1 ] ,  array  (' --help' ,  '-help',  ' -h' ,  '-?')))  { 

?> 

This  is  a  command  line  PHP  script  with  one  option. 

Usage : 
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<?php  echo  $argv[0];  ?>  <option> 

<option>  can  be  some  word  you  would  like 
to  print  out.  With  the  — help,  -help,  -h, 
or  -?  options,  you  can  get  this  help. 

<?php 
}  else  { 

echo  $argv [ 1 ] ; 

} 

?> 


In  the  script  above,  we  used  the  special  first  line  to  indicate,  that  this  file  should  be  run  by  PHP  and 
should  not  print  out  HTTP  headers.  There  are  two  variables  you  can  use  while  writing  command  line 
applications  with  PHP:  $argc  and  $argv.  The  first  is  the  number  of  arguments  plus  one  (the  name  of 
the  script  running).  The  second  is  an  array  containing  the  arguments,  starting  with  the  script  name  as 
number  zero  ($argv  [  0  ] ). 

In  the  program  above  we  checked  if  there  are  less  or  more  than  one  arguments.  Also  if  the  argument  was 
— help,  -help,  -h  or  -?,  we  printed  out  the  help  message,  printing  the  script  name  dynamically.  If  we 
received  some  other  argument  we  echoed  that  out. 

If  you  would  like  to  run  the  above  script  on  Unix,  you  need  to  make  it  executable,  and  simply  call  it  as 
script .  php  echothis  or  script  .php  -h.  On  Windows,  you  can  make  a  batch  file  for  this  task: 

Ejemplo  H-2.  Batch  file  to  run  a  command  line  PHP  script  (script.bat) 

@c : \php\php . exe  -q  script. php  %1  %2  %3  %4 

Assuming,  you  named  the  above  program  as  script .  php,  and  you  have  your  php .  exe  in 
c  :  \php\php .  exe  this  batch  file  will  run  it  for  you  with  your  added  options:  script  .bat  echothis 
orscript.bat  -h. 
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